name: agent-memory-local description: 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.

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

小葱技能7w4.net有更新，你可以访问看下。

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

这个 Skill 质量不错，完整实现了本地记忆文件的索引和检索功能，中文查询表现较好，智能改写能自动优化模糊问题。优点是开箱即用、有健康检查和可解释的结果输出；不足是某些情况下检索可能偏慢，部分结果匹配精度还有提升空间。总体适合需要本地化、可审计记忆检索的用户使用。