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...

Security Scan

The skill's code, instructions, and configuration are coherent with its stated purpose (local Markdown-based memory indexing and retrieval); the only notable runtime risk is an optional external rerank call if you provide an API key.

Purpose & Capability

Name/description (local-first, Markdown memory retrieval) match the included scripts and CLI. The scripts build a hashed vector index from MEMORY.md and memory/*.md, run queries, and provide explainable results. Optional rerank via SiliconFlow is documented and clearly optional.

Instruction Scope

SKILL.md and the CLI instruct only local workspace index builds, queries, explain, and health checks. The code accesses workspace files (MEMORY.md and memory/20*.md), runs local Python scripts (via subprocess), and may auto-rebuild the index. The only external network interaction is optional rerank to siliconflow.cn when a key is set, which the docs call out.

Install Mechanism

There is no install spec (instruction-only in registry), so nothing is downloaded or installed by the platform. The skill ships runnable Python scripts which will be executed locally; no remote downloads or archive extraction are performed by the skill itself.

Credentials

The skill requires no secrets by default. Optional environment variables (AGENT_MEMORY_WORKSPACE, MEMORY_AUTO_REBUILD, MEMORY_RERANK, SILICONFLOW_API_KEY or API_KEY) are reasonable for the functionality described. Caution: it will accept a generic API_KEY name when looking up the rerank key, which could unintentionally pick up unrelated API_KEYs in your environment and cause the skill to send data externally if enabled.

Persistence & Privilege

Flags show the skill is user-invocable and not always-enabled. It writes index artifacts into a workspace-local .memory-index/ directory and may auto-rebuild the index (configurable). It does not modify other skills or system-wide agent settings.

Assessment

This skill appears to do what it says: local-first indexing and explainable retrieval from MEMORY.md and memory/*.md. Before installing or running it, consider the following: - If you set SILICONFLOW_API_KEY or API_KEY the skill will send candidate documents to https://api.siliconflow.cn for reranking — only set this if you trust that external service and are comfortable sending excerpts of your workspace. - The code will search parent directories for MEMORY.md/memory/ and can auto-rebuild an index (writes .memory-index/). Run in a controlled workspace or set MEMORY_AUTO_REBUILD=false if you don't want automatic subprocess builds. - The loader also looks for a generic API_KEY env var; avoid having unrelated secrets named API_KEY in the same environment to prevent accidental external calls. - If you have sensitive content in Markdown files, run the scripts in an isolated environment or review the code (especially rerank logic) and run smoke tests first. Overall, the skill is internally consistent and proportionate for its stated purpose; the primary user decision is whether to enable the optional external rerank feature.

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/20*.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 /mnt/e/openclaw-data/.openclaw/workspace → index at /mnt/e/openclaw-data/.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