GoodMemory

GoodMemory

Language: English | [简体中文](./README.zh-CN.md)

GoodMemory is a memory layer for AI products and coding agents.

It gives chat apps, copilots, and agent hosts a durable user/project memory loop: write selected facts, retrieve the right context, inject it into the next turn, audit what happened, and delete it when it is wrong.

GoodMemory is not an LLM, agent framework, vector database, or generic RAG system. It is the product memory layer between your app or installed agent host and the model runtime.

What You Get

• Durable memory API: remember, recall, buildContext, feedback, forget,

exportMemory, and deleteAllMemory.

• Installed agent memory for Codex and Claude Code through goodmemory setup,

managed hooks, installed Codex pre-action, goodmemory status, read-only MCP, and opt-in writeback.

• Public write customization with GoodMemoryConfig.remember,

RememberProfile, rememberRules, RememberInput.annotations, and named extractor ids.

• Package exports for goodmemory, goodmemory/ai-sdk, goodmemory/host,

and goodmemory/http through compiled dist artifacts and TypeScript declarations.

• Local-first storage: Bun gets durable SQLite by default; explicit Postgres,

injected adapters, and embedding providers can be added when needed.

• Evaluation and release evidence paths for deterministic tests, live evals,

provider-backed evals, package smoke tests, and quality gates.

Start Here: Codex Or Claude Code

npm install -g goodmemory@0.5.1
goodmemory setup

No account or hosted service is required. GoodMemory stores memory locally in SQLite by default, wires lifecycle hooks plus read-only MCP inspection, and keeps durable writeback opt-in. Verify the installation with goodmemory status.

Using another MCP client or integrating an application? [Choose an integration path](#choose-your-integration-path).

Benchmark Results

GoodMemory separates current-production claims, versioned historical evidence, and internal research. A number may enter the current-claims table only after gate:public-benchmark-claim --strict validates a committed declaration for the current package version: complete coverage, executionFailures: 0, a no-memory baseline, deterministic scoring or an independent judge, verified dataset source and license, and a reproducible run (commit + command + package version). Historical rows remain under separate markers and cannot satisfy the current-version gate.

The Phase 72 v0.6.0 generalized refresh is still open. Current reruns do not show a uniform score increase: MemoryAgentBench CR/TTL are 0.9589041096/0.9333333333. ImplicitMemBench Full-300 scored 0.6683666667 and 0.6790333333 on two independent gpt-5.4 judging passes; an explicitly disclosed four-case LogiQL retry merge reached 0.6923666667 with zero failures, but remains internal evidence rather than a replacement full-run claim. BEAM's generalized full-400 evidence recall is 0.8273942646; a stored-retrieval retry after a generic subject-date guardrail raised the 20-case official-protocol slice from 0.7766666667 to 0.8266666667 (59/59 rubric items, zero judge failures). HaluMem's frozen slice now beats its local vector baseline on all three official metrics: extraction 0.9309950438 vs 0.8615384615, update 0.75 vs 0.625, and QA 0.8888888889 vs 0.7777777778. LongMemEval now has a current zero-failure full-500 goodmemory-recommended run with bounded, monotonic query-tail evidence expansion: gpt-5.6-terra answers score 340/500 = 0.680 under an independent gpt-5.4 official-protocol rescore, while its judge-free deterministic lower bound is 269/500 = 0.538. This raised the assistant category from 39/56 to 46/56 while every other category held within 1pt, but both headline tracks still miss the required 0.92 / 0.72 gates. LoCoMo's current full-1540 production run also misses its strict and official score gates. These remain internal research results, so the table below retains versioned historical evidence with its disclosed profiles.

Versioned historical claims (not current-production results)

These rows remain reproducible evidence for the disclosed package version and runtime profile. They are not claims about the current production-generalized path. The runtime capability descriptor keeps benchmarks.currentClaims empty until a current-version full gate explicitly promotes a replacement result.

| Benchmark | Primary metric | GoodMemory result | Baseline / reference | Claim declaration | |---|---|---:|---:|---| | LongMemEval full 500 | strict: judge-free deterministic subset · comparable: official LongMemEval judge protocol | strict 0.720 (360/500) · official-protocol 0.888 (444/500), goodmemory-rules-only | no-memory 0.068; current Mem0 harness: 94.4 Top200 / 94.8 Top50 (different stack and budget) | [longmemeval.json](./benchmark-claims/longmemeval.json) | | MemoryAgentBench (CR, TTL) | answer accuracy — deterministic, judge-free | CR 0.959, TTL 0.767 | no-memory ablation 0.000; published single-hop CR ceiling ~0.60 | [memoryagentbench.json](./benchmark-claims/memoryagentbench.json) | | LoCoMo (full 10 conversations) | strict: deterministic token-F1 · comparable: industry LLM-judge protocol (non-adversarial 1540) | strict 0.6117 (942/1540) · judge-protocol 0.837 (1289/1540) | no-memory 0.0045 non-adversarial; current Mem0 harness: 92.5 Top200 / 91.8 Top50 (different stack and budget) | [locomo.json](./benchmark-claims/locomo.json) | | BEAM 100K (400 questions, 1051 rubric items) | official BEAM rubric judge (1.0/0.5/0.0 per rubric item) · strict: internal binary judge | official-protocol 0.802 · strict binary 0.7225 (289/400) | no-pack ablation 0.5725; only public same-protocol reference: 0.49 | [beam.json](./benchmark-claims/beam.json) | | ImplicitMemBench Full-300 | stored-answer cross-version judge rescore | 0.691 (207.35/300), gpt-5.4 judge over gpt-5.5 answers, sourceAnswersUnchanged | upstream-chat baseline 0.400 (120/300); reference line 0.66 | [implicitmembench.json](./benchmark-claims/implicitmembench.json) |

Where both are available, each historical row reports two tracks. The strict track is deterministic or judge-free — a hard lower bound no LLM judge can inflate. The comparable track re-judges the same stored answers (not regenerated) under each benchmark's official or industry-standard judge protocol, verbatim, so the number sits on the same scale as published competitor results. The gap between the tracks is quantified judge leniency, disclosed instead of hidden. Comparable-track judging uses gpt-5.4 — a different model from the historical gpt-5.5 answerer but the same family; every per-protocol detail is recorded in the linked declarations.

The historical LongMemEval strict result is judge-free, replacing an earlier internal with-judge number (0.908) that is superseded and not claimable. A case counts as correct only when a deterministic method scores it (abstention / exact / contains / expectedalternative / numericcount); the eval pipeline's same-model semantic judge (gpt-5.5 judging gpt-5.5) is excluded by construction — with it, the diagnostic overall accuracy is 0.896, reported for transparency but not claimed. The recorded 0.720 (360/500, executionFailures: 0, v0.3.5) uses the embedding-free goodmemory-rules-only profile; abstention contributes only 28 of the 360 correct answers, while the no-memory baseline's 0.068 is mostly bare abstention (30 of its 34 correct), so the +65.2-point lift is the memory system's contribution. Judge-free refers to scoring — answers are still generated by gpt-5.5. Full provenance is in the [claim declaration](./benchmark-claims/longmemeval.json). The historical MemoryAgentBench declaration is deliberately scoped. It records only Conflict Resolution (CR 0.959) and Test-Time Learning (TTL 0.767): a no-memory ablation scores both 0.000 (the questions are unanswerable without GoodMemory's retrieved consolidated fact / in-context demos), so these are genuine memory contributions, scored deterministically with no LLM judge (executionFailures: 0, 259 questions). Accurate Retrieval and Long-Range Understanding are EXCLUDED: the no-memory ablation scores them higher (AR 0.926 vs 0.890; LRU 0.632 vs 0.518), so they are multiple-choice leaks where the model answers from the candidates in the question, not memory wins. CR/TTL measure answer-time current-value resolution and in-context retrieval, not general retrieval recall.

The historical LoCoMo strict result is scored by deterministic token-F1 (judge-free, executionFailures: 0 across all 1986 questions of the full 10-conversation set, v0.3.5). The profile is disclosed and opt-in — provider-embedding semantic candidate union (retrieval.semanticCandidates, topK 16) plus conversational write-time extraction plus an abstention-format answer prompt; the embedding-free default scores 0.020 on the representative conv-1 slice (the banked retrieval boundary), so this result is specifically about the embedding+extraction profile, not the zero-dependency default. Read the memory lift on the non-adversarial split (0.6117 vs 0.0045 — 942 vs 7 correct of 1540): the adversarial category (446 questions whose gold answer is the literal abstention string) is trivially aced by a no-memory arm that always abstains (0.998 vs 0.648 with memory), so the overall-vs-overall comparison (0.6198 vs 0.2276) understates the memory contribution on answerable questions. Answers are generated by gpt-5.5 — judge-free refers to scoring. The LoCoMo dataset is CC BY-NC 4.0 (non-commercial scope) and is fetched at eval time, never vendored. Full provenance is in the [claim declaration](./benchmark-claims/locomo.json).

The historical BEAM 100K result is retained as versioned evidence but is not a current public-claim row because its recall path used the repo-only legacy-fitted profile. It was scored under the benchmark's official unified rubric judge: each of the 1,051 rubric items is scored 1.0/0.5/0.0 and a question's score is the mean over its items (all 400 questions, judgeFailures: 0). The only public end-to-end BEAM 100K number scored the same way is 0.49; GoodMemory scores 0.802 (+31 points), with per-category detail in the declaration — including the one category below that reference (instructionfollowing 0.394 vs 0.66), disclosed rather than averaged away. The strict internal binary-judge track is 0.7225 vs a 0.5725 no-evidence-pack ablation (the answer-time evidence pack contributes +15 points). Recall is dual-metric per [ADR-005](./adr/ADR-005-scenario-fitted-recall-boundary.txt): rules-only fitted 0.9621 vs generalization floor 0.6822 with all 148 scenario-fitted gates disabled (the shipped opt-in semantic-candidate union lifts that floor to 0.8529). One protocol deviation is disclosed: the paper pipeline scores eventordering with a rank-correlation metric; both this run and the public reference rubric-judge it. Dataset CC BY-SA 4.0, fetched at eval time, never vendored.

The historical ImplicitMemBench Full-300 declaration uses the canonical zero-failure run-phase61-full300-rerun-20260706-codex-current answers, then re-scores the same stored answers with gpt-5.4 (sourceAnswersUnchanged: true). The judge is cross-version but the same GPT family as the gpt-5.5 answer model, not a cross-family judge. The recorded score is 0.691 (207.35/300) versus an upstream-chat baseline of 0.400 (120/300), with 530 judge-required row decisions across the baseline and GoodMemory arms; deterministic structured_first_action rows are carried forward rather than judged. The older same-model diagnostic score was 0.708 and is not the recorded result. The freshest clean answer-regeneration drift check after recent code changes scored 0.6895 with executionFailures: 0; it shows current checkout drift, not a replacement for the stored-answer comparability artifact. Dataset CC BY 4.0, fetched at eval time, never vendored.

Internal diagnostics (not public claims)

Blocked benchmark numbers stay out of the current-claims table until their declaration has candidate_public_claim status for the current package version and gate:public-benchmark-claim --strict passes. The underlying run reports live under gitignored reports/ and are reproducible from the run commands recorded in the declarations.

Use [task-board/00-README.txt](./task-board/00-README.txt) for execution order and [docs/GoodMemory-Current-Status-and-Evidence.md](./docs/GoodMemory-Current-Status-and-Evidence.md) for claim boundaries.

Choose Your Integration Path

GoodMemory has three primary product entry points. They are not the only APIs: lower-level surfaces such as goodmemory/host, custom stores, eval tooling, and runtime helpers support these paths. They are the README-level ways to decide how to start.

Autonomous agent? Start here

If you are an agent that wants to give yourself durable memory, match one path and run it. Machine-readable versions of this tree live in [llms.txt](./llms.txt) and [.well-known/goodmemory.json](./.well-known/goodmemory.json) (a deployed bridge also serves the descriptor at /.well-known/goodmemory.json).

• You are, or run inside, Claude Code or Codex →

npm install -g goodmemory@0.5.1 && goodmemory setup. Unsure what is already wired? Run goodmemory adopt (add --json for a machine-readable plan): it inspects .claude/, .codex/, and existing MCP config, then prints the exact next command for your environment.

• You speak MCP (Cursor, Windsurf, Cline, Claude Desktop, Gemini CLI,

OpenCode, or a custom client) → add the [standalone MCP server](#standalone-mcp-for-any-client); the two tools you need are goodmemory_get_context (recall) and goodmemory_remember (opt-in write).

• You are a framework agent or a backend → call the

[HTTP bridge](#pythonfastapi-http-bridge): hosted at goodmemory.vibenest.net or self-hosted with goodmemory-http-bridge --recommended (or GOODMEMORY_PROFILE=agent-recommended goodmemory-http-bridge); Python callers use pip install goodmemory-client.

The prose paths below expand each option.

1. Build Memory Into An Agent, Chatbox, Or Copilot

Use this when you own the product server and the model call. Install goodmemory in your Node/Bun service, create one memory instance, and pass a stable scope such as userId, workspaceId, sessionId, and optionally agentId.

The request flow is:

1. Before the model call, run recall() for the current scope and query.
2. Run buildContext() to turn recall hits into a prompt fragment.
3. Call your model with that memory context.
4. After the response, write selected signals with memory.jobs.enqueueRemember()

or remember().

1. Use feedback(), targeted reviseMemory(), forget(), and exportMemory()

for correction, deletion, and user audit.

If your server already uses Vercel AI SDK, use goodmemory/ai-sdk to wrap generateText() or streamText() instead of hand-wiring the whole loop. Start with [App Quickstart](#app-quickstart), then read [AI SDK Adapter](#ai-sdk-adapter) if you use AI SDK.

2. Add Memory To Codex Or Claude Code

Use this when you want an installed coding agent to remember project and user context without changing the agent itself. Install the global CLI and run goodmemory setup.

The installed-host flow is:

1. session-start injects a session brief; user-prompt-submit injects

per-prompt context (relevance-gated on fresh installs so low-signal prompts stay clean).

1. The Claude Code Stop hook captures each turn from the session transcript

(transcript_path) into governed writeback candidates — bounded, redacted, never raw transcripts; for Codex, goodmemory codex writeback --from-rollout feeds the newest session rollout through the same pipeline.

1. Codex pre-tool-use can deny or redirect risk

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hjqcan
• Source: hjqcan/GoodMemory
• License: MIT
• Homepage: https://www.npmjs.com/package/goodmemory

Install and usage instructions live in the source repository linked above.