ClawHub

Agent Memory Local

Local-first memory retrieval for Agent/OpenClaw workspaces. Use when the user asks about prior work, decisions, dates, preferences, root causes, todo history, or "what changed" questions and you want explainable retrieval from MEMORY.md + memory/*.md instead of a remote memory platform. Best for Markdown-based long-term memory, local audits, postmortems, and continuity across long-running assistant sessions.

Audits

Pass
ClawScanReview

Agentic behavior and permission review.

Static analysisPass

Pattern checks against bundled files.

VirusTotalPass

Multi-engine malware detections and file reputation.

Install

openclaw skills install agent-memory-local

Agent Memory Local

Overview

Search and explain facts from MEMORY.md and memory/*.md in a local workspace. agent-memory-local gives an agent a transparent, local-first memory layer for questions like “我们上次怎么定这个规则的？” or “昨天为什么飞书断联？” without depending on a hosted memory service.

Production note: this retrieval style has already been used in real OpenClaw operating workflows behind jisuapi.com and jisuepc.com. That is a proof point, not a dependency.

Why install this

Use this skill when you want to:

  • find prior decisions, root causes, and preference history from Markdown memory files
  • explain why a result matched instead of trusting a black-box memory API
  • keep retrieval local and rebuild the index inside the workspace

Best fit:

  • local or self-hosted agent setups
  • teams that store durable memory in Markdown
  • users who want transparent, inspectable memory retrieval instead of a black-box cloud memory service

Common Use Cases

  • Decision recall — “我们之前怎么定这个规则的？”
  • Incident review — “飞书昨天为什么断联了？”
  • Change tracking — “更新后为什么记忆搜索变了？”
  • Preference recall — “小红书配图策略现在怎么要求？”
  • Policy / guardrail checks — “敏感信息能不能写进日志？”

Quick Start

30-second first run

python custom-skills/agent-memory-local/scripts/agent_memory_local.py build-index
python custom-skills/agent-memory-local/scripts/agent_memory_local.py smart-query "飞书昨天为什么断联了" -k 3

Build the local index

python custom-skills/agent-memory-local/scripts/agent_memory_local.py build-index

Direct retrieval

python custom-skills/agent-memory-local/scripts/agent_memory_local.py query "昨天更新后为什么记忆搜索变了" -k 6

Smart natural-language retrieval

python custom-skills/agent-memory-local/scripts/agent_memory_local.py smart-query "飞书昨天为什么断联了" -k 6
python custom-skills/agent-memory-local/scripts/agent_memory_local.py smart-query "What changed in our memory retrieval route after yesterday's update?" -k 6

Health check / doctor

python custom-skills/agent-memory-local/scripts/agent_memory_local.py doctor

Explain why a result matched

python custom-skills/agent-memory-local/scripts/agent_memory_local.py explain "飞书昨天为什么断联了" --smart -k 3
python custom-skills/agent-memory-local/scripts/agent_memory_local.py explain "Why did Feishu disconnect yesterday?" --smart -k 3

Not the best fit

Use a different memory system if you need:

  • graph/relationship-heavy enterprise memory
  • multi-user hosted memory APIs
  • fully managed temporal knowledge graph systems

Core Capabilities

1. Local index build

  • Reads from:
    • MEMORY.md
    • memory/learnings.md (if present)
    • memory/YYYY-MM-DD.md
  • Splits Markdown into retrieval chunks
  • Builds a lightweight hashed vector index into .memory-index/ under the workspace root
  • Stores freshness metadata for auto-rebuild checks

2. Explainable retrieval

Returns:

  • top matched file + title + snippet
  • overlap count
  • semantic score
  • explain block with overlap terms / anchor hits / recency bonus
  • index freshness status
  • optional explain view for cleaner public-facing reasoning output

This makes it useful when the user asks:

  • “我们上次怎么定这个规则的？”
  • “昨天为什么飞书断联？”
  • “记忆检索主路由是什么时候改的？”
  • “关于这个需求之前有没有决定？”

3. Chinese-friendly anchors

The retriever is tuned for queries like:

  • 飞书 掉线
  • 记忆搜索 变了
  • 主路由 默认入口
  • 截图 宿主
  • duplicate plugin id
  • gateway timeout

It boosts domain phrases, recency, and strong anchors instead of relying only on generic vector similarity.

4. Smart query rewriting

smart-query rewrites and scores multiple candidate queries automatically. This helps with fuzzy questions like:

  • “昨天更新后为什么记忆搜索变了？”
  • “飞书昨天为什么断联？”
  • “主路由后来是不是改过？”

5. Optional rerank enhancement

If SILICONFLOW_API_KEY is available, retrieval can optionally rerank the best candidates via SiliconFlow rerank. If the key is missing, the skill still works locally.

Example Output

Example command:

python custom-skills/agent-memory-local/scripts/agent_memory_local.py explain "飞书昨天为什么断联了" --smart -k 2

Example result shape:

{
  "query": "飞书昨天为什么断联了",
  "used_query": "飞书 断联 duplicate plugin id gateway timeout",
  "results": [
    {
      "rank": 1,
      "file": "memory/2026-03-10-request-timed-out-before-a-res.md",
      "score": 0.5084,
      "why_matched": {
        "anchor_hits": ["duplicate plugin id", "gateway timeout", "断联", "飞书"],
        "overlap_terms": ["duplicate", "duplicate plugin id", "gateway", "gateway timeout"]
      }
    }
  ]
}

This is the point of the skill: not just “some memory results”, but a query rewrite + top hits + an explanation of why they matched.

Workflow

Workflow A — answer a memory question

  1. Run smart-query
  2. Inspect top 3-5 results and explain fields
  3. Open the source Markdown file if you need exact wording
  4. Answer with the retrieved fact, not with guesswork

Workflow B — prepare for long-running assistant memory

  1. Keep durable facts in MEMORY.md / memory/*.md
  2. Run build-index
  3. Use doctor to confirm index freshness
  4. Use query / smart-query as the workspace memory route

Workflow C — debug retrieval quality

  1. Run doctor
  2. Confirm workspace detection and index freshness
  3. Rebuild with build-index
  4. Retry with query
  5. If results are fuzzy, try smart-query

Configuration

Workspace resolution

The scripts resolve the workspace in this order:

  1. --workspace /path/to/workspace CLI arg
  2. AGENT_MEMORY_WORKSPACE env var
  3. current working directory or its parents
  4. the skill location's parent chain

Optional env vars

  • AGENT_MEMORY_WORKSPACE — force the workspace root
  • MEMORY_AUTO_REBUILD=0|1 — disable/enable auto rebuild when stale
  • MEMORY_RERANK=0|1 — disable/enable rerank
  • SILICONFLOW_API_KEY — enable rerank enhancement

Use --workspace when running outside the target repo and you want deterministic workspace selection.

Index location

The index is stored in .memory-index/ at the resolved workspace root, not inside the skill folder. Examples:

  • workspace /repo/project → index at /repo/project/.memory-index/
  • workspace E:/openclaw/.openclaw/workspace → index at E:/openclaw/.openclaw/workspace/.memory-index/

When to rebuild the index

Rebuild manually when:

  1. first run in a new workspace
  2. MEMORY.md or memory/*.md changed and you want immediate freshness
  3. doctor reports a stale index
  4. retrieval results look outdated or obviously off-topic
  5. you switched workspaces or restored memory files from backup

If MEMORY_AUTO_REBUILD=1, query flows may rebuild automatically when the index is stale.

Files in this skill

scripts/

  • agent_memory_local.py — top-level CLI entrypoint
  • build_index.py — builds .memory-index/
  • retrieve.py — direct retrieval engine
  • memory_query.py — smart rewrite + best-query selector
  • doctor.py — health / freshness checker
  • explain.py — cleaner explanation view for why results matched
  • benchmark.py — regression benchmark runner against representative memory queries
  • common.py — workspace and path resolution helpers

references/

  • architecture.md — design notes and tradeoffs
  • publish-plan.md — packaging / release checklist for ClawHub

When to prefer this skill over heavier memory platforms

Use agent-memory-local when you want:

  • local-first memory
  • human-readable Markdown memory source of truth
  • explainable retrieval
  • low dependencies
  • easy audits and backups

Prefer heavier systems (Mem0 / Letta / Graphiti / Zep-style approaches) when you need:

  • hosted memory APIs
  • multi-user context services
  • temporal knowledge graphs
  • relationship-aware graph retrieval
  • enterprise-scale memory orchestration