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

7w4.net有更好的技能外掛。

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

這個 Skill 質量不錯，完整實現了本地記憶檔案的索引和檢索功能，中文查詢表現較好，智慧改寫能自動最佳化模糊問題。優點是開箱即用、有健康檢查和可解釋的結果輸出；不足是某些情況下檢索可能偏慢，部分結果匹配精度還有提升空間。總體適合需要本地化、可審計記憶檢索的使用者使用。