Talewell

Every story has its well.

Plugin-first long-term memory for every agent platform.
Git-backed. Auditable. Portable. No vector database required.

Install · Hosts · Protocol · CLI · Host guide · Architecture

Why Talewell

Two systems shaped this design:

• A $2.5B AI assistant whose memory layer is nothing but git-tracked Markdown plus grep — crude, but inspectable, auditable, and rollback-able.
• OpenClaw's memory architecture — proven on the hard half: provenance tainting, recall-driven promotion, deterministic gates around bounded model consolidation.

It is plugin-first by design. Every major agent platform is plugin-shaped now; Talewell meets them there instead of asking them to change.

What it does

• Plain Markdown, real git history. One memory record = one file. Every write is a commit. Every fact is diff-able, rollback-able, and readable with cat.
• Deterministic recall. Relevance × recency decay × importance, computed locally. No model call, no network, no API key required to search your own memory.
• Provenance enforced. Content the user stated (owner) or you derived from it (agent) may be stored. Web pages, tool output, and other people (untrusted) are refused structurally — this is a security property, not a tuning knob.
• Corrections that stick. Superseding a record retires the old value from recall and from prompt injection, while git keeps the history.
• A link graph in plain files. Records reference each other with [[id]]; stable IDs and aliases make the corpus both navigable and greppable.
• Prompt injection built in. On OpenClaw, a companion plugin injects a compact index before every turn, so the agent starts already knowing what it knows.

Install

As an MCP server — works with anything that speaks MCP

{
  "mcpServers": {
    "talewell": {
      "command": "node",
      "args": ["/path/to/talewell/bin/talewell.mjs", "serve-mcp"],
      "env": { "TALEWELL_REPO": "/path/to/talewell-memory" }
    }
  }
}

Exposes six tools: memory_recall, memory_index, memory_get, memory_remember, memory_forget, memory_graph.

As an OpenClaw plugin — ambient memory

openclaw plugins install --link /path/to/talewell/adapters/openclaw/plugin --force --accept-capabilities
openclaw plugins enable talewell --accept-capabilities

Then grant conversation-hook access so the index can be injected:

{
  plugins: {
    entries: {
      talewell: {
        enabled: true,
        hooks: { allowConversationAccess: true },
        config: { repoPath: "/path/to/talewell-memory", inject: "index" },
      },
    },
  },
}

Restart the gateway. The agent's prompt now carries a memory index every turn.

As a file convention — the universal fallback

talewell install --host codex --dir .        # writes a managed block into AGENTS.md
talewell install --host claude-code --dir .  # CLAUDE.md + .mcp.json

Any host that reads a project instruction file can use Talewell with no plugin and no protocol support.

Hosts

| Host | Tiers | Instruction file | Verified | | --- | --- | --- | --- | | OpenClaw | native, mcp, file, cli | AGENTS.md | yes | | Claude Code | mcp, file, cli | CLAUDE.md | yes | | Codex | mcp, file, cli | AGENTS.md | yes | | OpenCode | mcp, file, cli | AGENTS.md | yes | | Pi Coding Agent | mcp, file, cli | AGENTS.md | yes | | Hermes | file, cli | AGENTS.md | yes | | Grok bot | file, cli | AGENTS.md | no | | Muse AI | file, cli | AGENTS.md | no | | DeepSeek harness | file, cli | AGENTS.md | no |

Run talewell hosts for the registry with evidence pointers. Unverified hosts use safe defaults rather than guessed config paths.

Per-platform setup recipes — including the general method for any host not listed — are in docs/HOSTS.md.

CLI

talewell init ./talewell-repo                                     # create a memory repo
talewell remember --text "Leo 不吃辣" --alias "饮食,辣,diet" --importance 7
talewell recall "订餐厅要注意什么"                                  # deterministic, no model
talewell get <id>
talewell correct <id> --text "updated value"                      # supersede, keeps history
talewell forget <id> --reason "user request"                      # removes, keeps git history
talewell graph <id> --depth 2                                     # follow [[links]]
talewell index --markdown                                         # compact catalog for injection
talewell health
talewell log --limit 20
talewell diff <id>
talewell rollback <commit> --yes
talewell bundle ./transfer.bundle                                 # cross-host transfer
talewell consolidate candidates.json                              # bulk, gated
talewell serve-mcp
talewell hosts
talewell install --host claude-code --dir .
talewell uninstall --host claude-code --dir .

All commands accept --repo

repo/
  amp.json                    manifest: schema version + policy
  memory/
    facts/          f-*.md
    entities/<type>/ e-*.md
    episodes/       ep-*.md
    procedures/     pr-*.md
    index.json      generated catalog (rebuildable)

---
id: f-m8k2x9a7q3
kind: fact
aliases: [吃饭, dining, 餐厅, 口味]
text: Leo 不吃辣
origin: owner
importance: 7
observedAt: 2026-09-15
links: [e-3n8k2, f-9x1m4]

Optional longer prose.

L1 kernel   TalewellStore — git-backed Markdown repo (zero npm dependencies)
L2 protocol remember · recall · search · forget · consolidate · graph
L3 adapters OpenClaw · MCP · file convention · ACP

node --test "tests/*.test.mjs"