Talewell keeps agent memory in git-tracked Markdown

One record, one file, one commit

Talewell stores a single memory fact in a single Markdown file, and every write becomes a git commit. The README describes the model as plain Markdown with real git history, and the effect is that a fact can be opened with cat, compared with git diff and reverted. Nothing about the corpus sits behind a hosted API, and the history of a statement survives even after the statement itself has been retired from recall. For teams that already keep prompts, configuration and infrastructure under version control, this is a familiar storage model rather than an exotic one. The cost is that the memory repository is a working directory you are responsible for: it has to be committed, backed up and reviewed like any other source tree.

Recall that never calls a model

Search happens locally. The ranking score is described as relevance multiplied by recency decay multiplied by importance, and the README states plainly that no model call, no network and no API key are required to search your own memory. That is worth pausing on: the ordering is deterministic, so the same query against the same repository returns the same result, and a memory lookup cannot fail because a provider had an outage or a rate limit. The trade-off is that ranking quality depends on how closely aliases match the wording of a query, and the project documentation does not publish a quality benchmark, so anyone expecting semantic matching should read the scoring rule before depending on it.

Origins the store refuses to keep

Provenance is enforced in the storage layer rather than configured as an option. Content the user stated is stored with origin owner, and content the agent derived from that is stored with origin agent. Content from web pages, tool output and other people is marked untrusted and refused structurally, and the README calls this a security property rather than a tuning knob. A system origin is refused as well, and there are no silent writes. The practical effect is that a scraping step or an ingested document cannot quietly become something an agent later recalls as fact. The flip side is rigidity: relaxing that rule means changing the code, which makes Talewell a poor fit for teams that want to park untrusted text for later human verification.

Running Talewell as an MCP server

The package is JavaScript, its bin entry points at bin/talewell.mjs, and the declared engine floor is Node 22.22.3 or newer, so check that before anything else. The most portable way to try it is as an MCP server, which works with any host that speaks MCP. Point the command at a local checkout and set TALEWELL_REPO to the directory that will hold the memory repository:

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

Six tools are exposed: memory_recall, memory_index, memory_get, memory_remember, memory_forget and memory_graph. A sensible first session is to store one short statement with memory_remember, query it back with memory_recall, and then run memory_index to see the compact catalog that gets injected into a prompt.

The file convention fallback for hosts without plugins

Talewell also works where there is no plugin system and no protocol support, by writing a managed block into a host's instruction file. For Codex that file is AGENTS.md; for Claude Code it is CLAUDE.md plus .mcp.json:

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

OpenClaw is the deepest integration, because the README documents a companion plugin that injects a compact index before every turn, so the agent starts each turn already carrying its memory index:

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

Granting conversation-hook access is a separate step from enabling the plugin, and the plugin configuration carries a repository path plus an inject setting. The trade-off is that the file convention is the least capable tier: it puts instructions in place, but it cannot inject an index per turn.

The AMP repository layout and what rollback looks like

A Talewell repository is a directory holding an amp.json manifest and a memory/ tree. The manifest carries a schema version and a policy. Inside memory/, records are grouped by kind, with facts, entities organized by type, episodes and procedures, each file carrying a prefixed identifier, alongside a generated index.json catalog that can be rebuilt. The README keeps the product and the format deliberately separate: AMP, the Agent Memory Protocol, is the portable contract, and Talewell is one implementation of it, which is the reason a cross-host bundle is possible. Day to day, the interesting commands are the forensic ones:

talewell init ./talewell-repo                                     # create a memory repo
talewell get <id>
talewell diff <id>
talewell rollback <commit> --yes

Because each write is a commit, a bad memory is repaired by moving history rather than by editing a database row.

Where Talewell is the wrong tool

Talewell is the wrong choice when recall is a semantic problem rather than a lexical one. The kernel runs with no vector search and no API key, and embeddings are described as an optional layer, so a corpus whose records share no keywords with the incoming query will not surface the right record from the deterministic score alone. A hosted vector store answers a question about meaning, and pays for that with an embedding model, a network dependency and a second system to operate. Talewell keeps the corpus in files you can read, but it matches on aliases and keywords, so a record nobody worded similarly may stay invisible. Host coverage is the second limit. The host table marks OpenClaw, Claude Code, Codex, OpenCode, Pi Coding Agent and Hermes as verified, while Grok bot, Muse AI and the DeepSeek harness are marked unverified, and unverified hosts fall back to safe defaults instead of guessed configuration paths.

Editorial conclusion

Adopt Talewell when your agents need durable memory that outlives a single host session and you want the corpus readable as Markdown under git control. Skip it when recall must work on meaning rather than keywords, or when you need untrusted text stored verbatim. Before committing, verify three concrete things: that Node 22.22.3 or newer is present in your runtime, that the host you actually run appears in the host table with the tier you need, and what `talewell health` reports on a repo created by `talewell init`.

Frequently asked questions

Official sources

1. LeoYeAI/talewell on GitHub
2. License: MIT
3. Project website
4. README
5. Releases