LeoYeAI/talewell

TL;DR

Talewell is a plugin‑first, git‑backed long‑term memory system for AI agents. It stores each memory record as a plain‑text Markdown file in a Git repo, giving you full version history, diff‑ability, and auditability without needing a vector database. The system speaks a simple AMP (Agent Memory Protocol) that any host (OpenClaw, Claude Code, Codex, etc.) can implement, letting agents recall facts deterministically based on relevance, recency, and importance.

---

What it is

• Memory layer: One Markdown file = one memory record (fact, entity, episode, procedure). Every write creates a Git commit, so you can roll back, diff, and audit changes.
• Protocol: AMP defines a portable JSON manifest (amp.json) and a fixed on‑disk layout (memory/…). Hosts interact via six MCP tools (memory_recall, memory_index, …) or via a CLI.
• Deterministic recall: No embeddings or external API calls are required. Recall scores are computed locally from relevance × recency decay × importance.
• Provenance enforcement: Only content the user (owner) or the agent itself may be stored. Untrusted sources are rejected by design.
• Plugin‑first: Adapters exist for OpenClaw, Claude Code, Codex, and a generic file‑convention fallback, making the same memory repo usable across platforms.
• Link graph: Records can reference each other with [[id]] links, enabling graph traversal and a compact index that can be injected into prompts.

---

Who might use it

• Developers of AI assistants who want an auditable, offline‑first memory store that works with any agent framework.
• Teams concerned about data provenance and want a built‑in gate that blocks untrusted writes.
• Open‑source AI platform maintainers (e.g., OpenClaw, Claude Code) looking for a common memory backend without locking into a vector DB.
• Researchers experimenting with deterministic recall strategies or studying the impact of versioned memory on agent behavior.

---

How it works (high‑level)

1. Initialize a repo – talewell init ./my‑memory creates a directory with amp.json and a memory/ tree.
2. Add records – talewell remember --text "Leo 不吃辣" --alias "饮食,辣,diet" --importance 7 writes a Markdown file (f‑*.md) and commits it.
3. Recall – talewell recall "订餐厅要注意什么" scans the repo, scores each fact, and returns the best match—all offline.
4. Correct / Forget – Supersede a fact with correct (keeps history) or remove it with forget (still retained in Git for audit).
5. Graph & Index – talewell graph <id> follows [[link]] references; talewell index --markdown builds a compact catalog that can be injected into an agent’s prompt each turn.
6. Serve via MCP – talewell serve-mcp launches a server exposing the six memory tools, allowing any MCP‑compatible host to call them.
7. Cross‑host transfer – talewell bundle ./transfer.bundle packages a repo for moving between platforms.

---

What’s missing / open questions

• Embedding layer – The core deliberately avoids vector search; adding embeddings is optional and not part of the baseline.
• Scalability – Git works well for moderate‑size corpora, but very large memory stores may hit performance limits.
• Host ecosystem – Only a handful of hosts are listed as “verified”; others rely on safe defaults.
• Security model – Provenance enforcement blocks untrusted writes, but the README does not detail authentication for the MCP server.

---

Quick start (CLI)

# 1. Create a memory repo
talewell init ./talewell-repo

# 2. Remember a fact
 talewell remember \
   --text "Leo 不吃辣" \
   --alias "饮食,辣,diet" \
   --importance 7

# 3. Recall something
 talewell recall "订餐厅要注意什么"

# 4. Serve for a host (e.g., OpenClaw)
 talewell serve-mcp

---

License

MIT – free to use, modify, and redistribute.