Durable memory for daily AI coding · 1-second recall · Trustworthy confidence levels · Anchor-based freshness · Optional token-goat seam

Local-first, defense-in-depth memory that remembers what your AI coding agent keeps forgetting between sessions.

You tell your AI "we use pnpm not npm" and it forgets. Every session. Then it runs npm install and corrupts the lockfile. You re-explain that you prefer 2-space indentation, and the next day it defaults to tabs. These are not oversights — the agent genuinely does not see a record of these decisions after a compaction.

Mem stores them. Locally, in your own SQLite database. Each fact carries a trust level and an anchor (a read-only predicate that tests whether the fact is still true). On recall, Mem re-validates anchors and surfaces only the facts that are fresh and trustworthy, with a confidence caveat so your agent never treats a hint as ground truth when it should not.

Works with Claude Code, Copilot CLI, Copilot in VS Code, Codex, and any agent that can run a shell command — integration guides for the first four live in docs/integrations/. There is also an optional seam -- a one-way integration point, where the other tool calls mem and mem knows nothing about it -- with token-goat, a sister CLI that gives agents narrow-slice code/doc reads to cut context burn. Token-goat reads mem epoch (a cache-invalidation key) and optionally consumes memory via the published TGMEM/2 wire format, which a future host tool can adopt.

Install:

npm install -g token-goat-mem
mem --help

Building from source, requirements, and verifying the install: Install.

Built and maintained by DFK Helper. Free under PolyForm Noncommercial. If it saves your tokens, or your sanity, drop a star at the top of this page.

Install · CLI · Walkthrough · How it works · Anchors · Token-goat integration · Disclaimer & License

Your AI coding agent accumulates durable knowledge that keeps evaporating:

• Preferences — "uses pnpm not npm", "2-space indent", "no default exports", "tabs not spaces"
• Decisions — "chose Postgres over Mongo for relational queries", "auth service owns migrations"
• Project facts — "staging DB is at prod-staging-db-1", "CI env is GitHub Actions"
• Corrections — recurring "do not do X" that you repeat every session

Today this knowledge is lost at each session boundary. The agent re-asks, re-derives, or — worst — forgets and does the wrong thing. A confident wrong memory is worse than no memory at all. If Mem surfaces a stale preference as ground truth ("you use npm" three months after you switched to pnpm), your agent acts on it and corrupts your lockfile.

The defining engineering problem is not retrieval — it is correctness and staleness. Mem solves both.

1. Explicit capture — mem remember "uses pnpm not npm" --kind preference stores a fact with a source reference (source_ref: where the fact came from, such as the command or file that produced it -- not to be confused with the separate sources table mem show --json exposes, which is designed to hold redacted content previews and is not yet written to by any capture path) and timestamp. --kind is required: preference, decision, fact, or correction. Saying the same thing again reaffirms the existing fact rather than writing a second row: captured_at and confidence are refreshed, and the command prints reaffirmed instead of remembered. Matching is deterministic and conservative -- same normalized text (case folded, whitespace collapsed, one trailing period dropped), same kind, same scope binding, same subject and value (value compared case-insensitively with internal whitespace collapsed, same as contradiction detection below, though the raw value you typed is always what gets stored and shown) -- so identical text carrying a genuinely different value stays two facts for contradiction resolution to key on. Only live facts match: a pending one is never reaffirmed (that would promote it without review), a superseded one is never resurrected, and mem suggest never reaffirms at all, since derived text must not refresh a fact the user did not restate.
2. Optional anchors — Add an anchor: mem remember "uses pnpm" --kind preference --anchor 'file-newer-than pnpm-lock.yaml package-lock.json'. The anchor is a read-only predicate; on recall, Mem tests it and returns one of three verdicts: affirmed (ground truth), unverified (hint to verify), or contradicted (suppressed, flagged in review).
3. Recall with trust levels — mem recall --kind preference returns active facts annotated by trust level, freshness verdict, and age. Low-trust facts are marked "verify" so your AI never mistakes a hint for ground truth.
4. Review and resolution — mem review lists pending, contested, and anchor-contradicted facts. The two words are different mechanisms and both appear throughout: contested is fact-versus-fact (two facts disagree with each other, and neither clearly wins), while contradicted is fact-versus-world (an anchor predicate tested reality and denied the fact). A fact can be either without being the other. Contradictions (same subject + scope, different values, ambiguous winner) are never surfaced as ground truth — they appear here for you to resolve. Resolution runs both ways: once the rival is forgotten or edited into agreement, the next mem epoch --gc reinstates the survivor (back to pinned if it was pinned) instead of leaving it withheld.
5. Forget and edit — mem forget <id> soft-deletes a fact (marks it superseded, kept for audit); mem edit <id> updates text, subject/value, anchor, or scope, and mem edit <id> --undo walks the last edit back. Both bump an internal epoch so the token-goat seam always sees the latest state.

Requirements: Node.js 18 or later

npm install -g token-goat-mem

Or from source:

git clone https://github.com/DFKHelper/token-goat-mem.git
cd token-goat-mem
npm install
npm run build
npm link

No daemon, no tray icon, no setup wizard. Mem is a short-lived CLI process.

mem --version
mem epoch

mem --version prints the installed version; mem epoch prints a number (creating the database on first run), which confirms the CLI and the SQLite store are wired correctly.

Everything is stored in a single SQLite database at ~/.mem/mem.db. Set TOKEN_GOAT_MEM_HOME to relocate it (the test suite uses this to isolate itself from your real data). No network calls, ever.

On POSIX systems the directory is created 0700 and the database 0600, so the store is readable only by you even on a shared machine -- and an existing home created by an earlier version is tightened on the next run. Windows relies on the ACL ~/.mem inherits from your user profile, which restricts it the same way.

Every <id> argument (show, forget, pin, edit, used, review --promote/--reject) accepts a git-style short prefix — at least 4 characters — instead of the full id, as long as it uniquely identifies one fact. A prefix matching more than one fact errors and lists every match.

Every command supports --help for the authoritative flag list.

Retrieval is BM25 (lexical) by default and needs no configuration. Point these at any OpenAI-compatible embeddings endpoint -- OpenAI, Ollama, LM Studio, LiteLLM -- and recall additionally ranks by meaning, fusing the two lists with Reciprocal Rank Fusion:

A localhost endpoint keeps mem's zero-network property; a hosted one does not, and sends your fact text to that provider. Nothing is sent until you set the URL.

Once configured, mem remember and mem suggest embed each new fact in the background of the same command -- after secret screening, never before -- and never fail, slow, or change their output if the endpoint is down. Run mem embed once to backfill facts captured earlier.

Vectors from two different models are not comparable, and cosine similarity cannot detect the mismatch: it happily compares them and returns a confident, meaningless number. Mem records which model produced the store's vectors and refuses to rank against them when the configured model differs, saying so on mem recall and mem doctor. mem embed --all is the migration.

mem consolidate can tell that two facts restate each other; it structurally cannot tell that a third thing follows from both, because Jaccard over topic terms has no notion of entailment. mem dream asks a model that question and prints the answer. Same shape as semantic recall above -- off until you set the URL, any OpenAI-compatible chat-completions endpoint:

It writes nothing, and no flag makes it. The output is a report; anything in it worth keeping is kept by typing mem remember, which runs the same secret screening, anchoring, and contradiction checks every other fact goes through. That is the whole design: a model is allowed to suggest what might follow from the store, and is never allowed to add to it.

It sends stored fact text to a chat model, when configured. Semantic recall/capture sends fact (and query) text to an embeddings endpoint too, when TOKEN_GOAT_MEM_EMBED_URL/_MODEL are set -- dreaming is not unique in this, it is just the other opt-in path that reaches off this machine. Point either at a local model if the store holds anything you would not paste into a hosted API.

Only active and pinned facts are sent, newest first, capped at 200 -- a superseded fact is one the store has already decided is wrong, and an inference resting on it would carry the store's authority behind a retracted premise. The reply is treated as untrusted input rather than as an answer: a candidate must cite at least two of the facts actually sent, by an index that resolves, and must not restate a fact already stored. One that fails any check is dropped rather than printed, so every from: id is one mem show opens.

$ mem dream
dream: qwen3:8b via localhost  facts_sent=34
2 candidate inference(s) -- nothing was written; this is a report
  [fact] deployment is entirely manual end to end
    from: 3f2a... 9c14...

mem import --from-json and scope_root: a scope="project"/scope="path" fact's scopeRoot is an absolute filesystem path from the machine it was exported on. mem import --from-json imports it verbatim (full fidelity), so re-importing an export from a different machine — or a different path on the same machine — leaves scopeRoot pointing at a path that may not exist there. For a scope="project" fact captured inside a git checkout with a remote, the scope_repo identity below covers that case and the fact still surfaces; a scope="path" fact, or a project fact from a checkout with no remote, still binds to the path alone.

Project identity (scope_repo): a scope="project" fact captured inside a git checkout also records <normalized remote>#<root relative to the working tree>, so it surfaces from a second clone of the same repository, from a git worktree, and after an export/import onto another machine. The subpath half is what keeps a monorepo honest: one remote, many project roots, so packages/a and packages/b are different projects and neither sees the other's decisions. Identity only ever widens recall — the absolute-path binding is checked first and unchanged, and a fact with no identity (captured before this existed, or in a checkout with no unambiguous remote) is matched by path exactly as before. Reading is local and read-only: git is never invoked, only .git's own files are parsed. Set TOKEN_GOAT_MEM_PROJECT_IDENTITY=path to opt out and keep the path-only binding at both capture and recall — the case for it is two clones that are deliberately not the same project, such as a fork kept for experiments.

Contradiction resolution deliberately still keys on scope_root, not scope_repo: that key decides the persisted superseded/contested transitions, there is no honest backfill for facts captured before identities existed, and widening it would rewrite facts across checkouts on the first mem epoch --gc after upgrade. The cost is stated plainly — two facts on one subject captured in two clones are both in scope and are not detected as rivals.

Paste this into a terminal (uses a throwaway home so it never touches your real data):

export TOKEN_GOAT_MEM_HOME=$(mktemp -d)

mem remember "uses pnpm, not npm" --kind preference --subject package-manager --value pnpm
# remembered preference fact 79bce136-679f-471b-8ccb-fd18df7d2b36

mem remember "switched to bun" --kind preference --subject package-manager --value bun
# remembered preference fact 21a1330e-95d3-453c-81f0-49c792e1488f

mem recall
# stored pref (unverified, 2026-07): switched to bun
# mem show <id> for detail

Both facts share the subject package-manager with different values — a contradiction. Recall already prefers the newer fact and hides the loser; epoch --gc persists that resolution:

mem epoch --gc
# epoch=3  contradictions_resolved=1  preferences_decayed_below_floor=0  pruned_superseded_facts=0  pruned_sources=0  pruned_audit_log_rows=0  pruned_recall_log_rows=0

mem list
# 21a1330e-...  [preference/active] package-manager=bun  switched to bun
# 79bce136-...  [preference/superseded] package-manager=pnpm  uses pnpm, not npm

Anchored facts are re-validated on every recall. An anchor that tests false excludes the fact from ground truth and routes it to review:

mem remember "repo has a yarn.lock" --kind fact --anchor "file-exists yarn.lock" --scope project --root .

mem recall --root . --scope project
# fact (contradicted, excluded): repo has a yarn.lock
# mem show <id> for detail; mem review to resolve contested/pending

mem review --root .
# -- anchor-contradicted (suppressed from ground truth) (1) --
# 888ba2c0-...  [fact/active]  repo has a yarn.lock

(IDs are random UUIDs; yours will differ.)

Anchors are pure, read-only filesystem/git predicates — no shell-out, no network, bounded I/O, and paths are confined to the given --root:

Each evaluation yields affirmed, unverified (missing file, no repo, malformed predicate — cannot confirm or deny), or contradicted. Only affirmed is ground-truth eligible.

Mem works standalone. When token-goat is on PATH, token-goat reads mem epoch (a monotonic integer) to invalidate its compaction cache. The TGMEM/2 wire format is published as an optional seam for host tools to adopt; token-goat does not consume it today. It is not unused, though: mem init claude-code installs hooks that run mem recall --hint-format on SessionStart and UserPromptSubmit, so the format is what mem emits into Claude Code on every session and every prompt.

The seam is one-directional (Mem reads nothing from token-goat), stateless (live calls, no caching), and self-caveating (display strings include their own trust caveats). Contested or low-trust facts are excluded from --hint-format entirely — only ground-truth-eligible or explicitly-caveated hints are emitted. Mem does not cache results; forget/edit reflect instantly. If mem is not on PATH or the call times out, token-goat falls back to no hints (fail-open).

--hint-format emits TGMEM/2 by default: a header line, then one line per fact (pref fresh=affirmed|unverified|contradicted id=<uuid> display="<caveated text>"), then at most one shared footer line naming what is worth following up on: footer mem show <id> for detail, extended with N more in scope, not sent when the per-kind caps dropped results (2 of the block's 14 lines are reserved for pinned facts before those caps see the list, so a pin always arrives even against a full set of better-matching facts), N withheld; mem review to resolve contested/pending when facts were held back from ground truth, and no match for this query -- showing recent facts instead when a non-empty query matched nothing at all -- no lexical hit, no embedding or usefulness signal either -- so every fact-line the response does carry is filler the caps swept in by recency, not an answer to the query. Those counts exist because their absence is unfalsifiable from the wire — a capped payload is byte-identical to a complete one, and a response with no fact lines is byte-identical to a project with no memory, even while a review queue fills behind it. The footer is prose for a reader, not a parseable field; a response with nothing to follow up on carries none. When the store itself could not be opened -- a permissions failure, a WAL lock, a schema mismatch -- the response is still TGMEM/2 with zero fact lines, but the footer says footer store could not be read; mem doctor shows the underlying error instead of carrying nothing at all: mem doctor runs the same call that just failed, but answers to a human on stderr instead of failing open onto the wire. The same reasoning covers the other two ways this call can go silent without there being nothing to say: a soft retrieval time budget cutoff returns zero fact lines (never a smaller slice -- TGMEM/2 has no way to mark a response partial, so a reduced set would be byte-identical to a complete one) with a footer saying footer hint set empty; retrieval ran out of its time budget, not out of facts -- mem recall shows them, and an internal error downstream of a successful store open carries footer hints unavailable; an internal error stopped retrieval -- mem doctor shows the store state.

TGMEM/2 moved the per-fact follow-up hint (mem show <id>, resolve via mem review, ...) out of every display string and into that one footer line, since repeating the same CTA on every line was pure overhead once a consumer already knows the pattern. display itself is unchanged otherwise — still self-caveating, still meant to be surfaced verbatim.

TGMEM/1 (the original format: per-line CTA baked into display, no footer line) remains fully supported for callers that still parse it — pass protocolVersion: 1 to buildHintFormat() when calling the programmatic seam directly. The CLI itself always emits the current default version.

Re-running mem recall --hint-format on every host-tool turn works, but it re-opens the DB and re-runs retrieval every time even when nothing changed. mem epoch is the cheap alternative: it prints a single monotonic integer that is bumped by every write that can change what a recall returns (remember, edit, forget, pin, review --promote/--reject, used, facets, the epoch --gc retention pass) and left untouched otherwise.

A host tool can use mem epoch to detect store changes and only re-run mem recall when the store actually changed. However, the epoch covers store writes only — it does not cover anchor verdicts (filesystem and git state, re-evaluated live on every recall) or preference decay (a function of time). A polling consumer should therefore either call mem recall on a time interval to refresh anchors and decay, or monitor for working-tree events (branch switches, dependency installs) that may invalidate anchors.

Store-only polling pattern (refreshes store state only):

last_epoch=$(mem epoch)
# ... later, on each turn ...
current_epoch=$(mem epoch)
if [ "$current_epoch" != "$last_epoch" ]; then
  mem recall --hint-format --root "$project_root"
  last_epoch="$current_epoch"
fi

Time-interval pattern (refreshes all state including anchors and decay):

last_recall=$(date +%s)
# ... on each turn ...
now=$(date +%s)
if [ $((now - last_recall)) -gt 300 ]; then  # 5 minutes
  mem recall --hint-format --root "$project_root"
  last_recall=$now
fi

mem epoch with no flags never mutates facts (no GC pass, no writes) — it is safe to call as often as you like as a cheap store-state check.

Integration guides in docs/integrations/:

• Claude Code
• Copilot CLI
• Copilot in VS Code
• Copilot in Visual Studio
• Copilot in JetBrains IDEs
• Codex

Any other agent that can run a shell command (Cursor, Windsurf, Cline, Aider, ...) can use the same patterns: mem recall --hint-format at session start, mem remember as decisions land.

Token-Goat Mem runs on your machine and writes to your local SQLite database. The software is provided as-is, without warranty of any kind. DFK Helper LLC is not liable for any damages arising from use. Full terms, including the No Liability clause, are in the LICENSE file.

Mem stores facts you tell it to remember and suggests candidate facts for confirmation. Never persisted by default: secrets, credentials, PII, high-entropy tokens, full file contents. Enforcement layers: (a) only short extracted facts are stored; (b) secret-pattern and entropy screening; (c) suggested facts shown in mem review before surfacing. Local-only by default: with neither TOKEN_GOAT_MEM_EMBED_URL/_MODEL nor TOKEN_GOAT_MEM_DREAM_URL/_MODEL set, nothing leaves this machine. Set the former and mem remember/mem suggest/mem embed send fact text and mem recall sends the query text (including every prompt, if wired via a coding tool's UserPromptSubmit hook) to that endpoint; set the latter and mem dream sends stored fact text to it. Run mem review to audit all stored facts.

Token-Goat Mem is source-available under the PolyForm Noncommercial License 1.0.0.

Personal use: free. Includes hobby projects, individual productivity, personal study, and private coding. Individual developers may install and use the software on their own machines for individual productivity purposes without a commercial license.

Commercial use or shared infrastructure: requires a license. Contact token-goat@dfkhelper.com for details.

Patent Pending.

Full terms in LICENSE.

Built and maintained by DFK Helper. If it saves your tokens or your sanity, a star means the world.