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

Build the local index

Direct retrieval

Smart natural-language retrieval

Health check / doctor

Explain why a result matched

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:

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

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

• - INLINECODE8
• INLINECODE9
• INLINECODE10
• INLINECODE11
• INLINECODE12
• INLINECODE13

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

4. Smart query rewriting

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

5. Optional rerank enhancement

Example Output

Example command:
CODEBLOCK6

Example result shape:
CODEBLOCK7

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. 1. Run INLINECODE16
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. 1. Keep durable facts in MEMORY.md / INLINECODE18
2. Run INLINECODE19
3. Use doctor to confirm index freshness
4. Use query / smart-query as the workspace memory route

Workflow C — debug retrieval quality

1. 1. Run INLINECODE23
2. Confirm workspace detection and index freshness
3. Rebuild with INLINECODE24
4. Retry with INLINECODE25
5. If results are fuzzy, try INLINECODE26

Configuration

Workspace resolution

1. 1. --workspace /path/to/workspace CLI arg
2. INLINECODE28 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
• INLINECODE30 — disable/enable auto rebuild when stale
• INLINECODE31 — disable/enable rerank
• INLINECODE32 — enable rerank enhancement

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

Index location

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

When to rebuild the index

1. 1. first run in a new workspace
2. INLINECODE39 or memory/*.md changed and you want immediate freshness
3. INLINECODE41 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
• INLINECODE44 — builds INLINECODE45
• INLINECODE46 — direct retrieval engine
• INLINECODE47 — smart rewrite + best-query selector
• INLINECODE48 — health / freshness checker
• INLINECODE49 — cleaner explanation view for why results matched
• INLINECODE50 — regression benchmark runner against representative memory queries
• INLINECODE51 — workspace and path resolution helpers

references/

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

When to prefer this skill over heavier memory platforms

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