GoodMemory

GoodMemory

Language: English | 简体中文

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

Release source: this source targets the 0.8.3 stable release.

Registry commands require goodmemory@0.8.3 to be published. The release

workflow verifies npm latest and the already published GitHub assets

against the locally prepared manifest; it does not rebuild or publish.

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, importMemory, 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.

OpenAI Build Week 2026

Pre-existing foundation. GoodMemory existed before OpenAI Build Week. The pre-event foundation already included the core memory API, local SQLite/Postgres storage, installed-host integration, and the local Inspector. The hackathon entry is the work added after the submission period opened on July 13, 2026, not the entire repository.

Added during Build Week. Dated commits completed and published v0.6.0, strengthened generalized retrieval and iterative-recall verification, added claim-source provenance coverage, hardened installed-host canaries and leakage audits, and expanded the controlled Codex coding-effect evaluation path. Review the pre-event-to-Build-Week diff and its dated commit history for the exact boundary.

How Codex and GPT-5.6 were used. Codex with GPT-5.6 was the primary implementation and verification environment: exploring the repository, implementing and reviewing changes, writing regression tests, reproducing installed-host behavior, and exercising the release and coding-effect evidence paths. GPT-5.6 also powers disclosed non-judge model calls in current evaluation profiles; public-claim paths either use deterministic scoring or keep the judge independent from the answer model.

Run and verify. After publication, install 0.8.3 from the registry and inspect its local memory surface:

npm install -g goodmemory@0.8.3

goodmemory setup --host codex goodmemory status codex --workspace-root . goodmemory inspector serve

Verify the repository from source with bun install --frozen-lockfile, bun test, and bun run typecheck. See the Devpost submission and public demo video.

Claim boundary: the submission demonstrates durable cross-session memory, governed writeback, recall evidence, and inspection/deletion infrastructure. It does not claim that GoodMemory has already proven an improvement in Codex coding outcomes; that paired hidden-test evaluation remains an active, fail-closed evidence track.

Start Here: Codex Or Claude Code

npm install -g goodmemory@0.8.3

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.

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). No end-to-end benchmark runner is allowlisted today, so promotion is unavailable for both current and historical rows. Stored-answer rescores and legacy presentation projections cannot open that boundary or supply README score and disclosure fragments as self-attestation.

GoodMemory 0.8.3 has no current or versioned historical benchmark claim. The retained v0.7.3 LoCoMo projection is not end-to-end runner evidence, so it is an internal diagnostic. The v0.6.0 LoCoMo, BEAM, and MemoryAgentBench measurements and ImplicitMemBench are also internal diagnostics under the same fail-closed boundary. LongMemEval is withdrawn pending a clean rerun: the historical rules-only path used answer annotations, and the later label-free path exposed raw answer_* session IDs to retrieval and the reader. ImplicitMemBench's retry-merged result remains internal evidence because it does not replace a monolithic fresh run. HaluMem, MemGym, and MINTEval remain release evidence rather than public benchmark claims.

No benchmark result is currently presented as measured on 0.8.3.

Versioned evidence

No end-to-end benchmark runner is currently allowlisted for versioned evidence.

No benchmark result currently qualifies as versioned historical evidence.

The retained v0.7.3 LoCoMo projection remains available in the repository for audit, but it is not shipped as a verified package artifact and cannot authorize a public or versioned claim. Old artifacts will not be retrofitted; a future producer and its verifier must be implemented together before promotion opens.

Where both are available, a row reports two tracks. The strict track is deterministic or judge-free — a hard lower bound no LLM judge can inflate. The second track re-judges the *same stored answers* (not regenerated) under a benchmark-source or industry-standard prompt. Numerical comparability is claimed only when the pinned evaluator model and remaining benchmark configuration also match. Every per-protocol detail is recorded in the linked declarations.

The LongMemEval declaration is now paused_boundary, not historical evidence. Its old numeric artifacts remain only to preserve the audit trail. They must not be quoted as GoodMemory results until an opaque-session-id, label-free full rerun replaces them; see the withdrawal declaration. The v0.6.0 BEAM, MemoryAgentBench, and LoCoMo measurements remain internal diagnostics. They do not pass the empty end-to-end runner allowlist, so they are not versioned historical evidence.

The ImplicitMemBench Full-300 stored-answer rescore 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. Its measured sources do not independently expose both package version and commit at explicit JSON paths, so the result is paused as an internal diagnostic and is not versioned historical evidence. Dataset CC BY 4.0, fetched at eval time, never vendored.

Internal diagnostics (not public claims)

LongMemEval's first current-recall assembly development slice is superseded: although its reader context hid raw session IDs, the memory-builder boundary still received gold-bearing session IDs and turn markers. A stricter v2 protocol now removes answers, question type, answer markers, and raw session identities before memory construction. Its development slice must be rerun on a clean commit before the still-sealed holdout can be opened; no LongMemEval claim is restored. ImplicitMemBench's explicit retry-merged check reaches 0.6923666667 with zero failures, but it is not a replacement monolithic fresh Full-300 run. Both therefore remain outside the current-claims table. The underlying reports live under gitignored reports/ and are reproducible from the recorded commands.

Use task-board/00-README.txt for execution order and 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 and .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.8.3 && 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; 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: 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().
5. Use feedback(),