GoodMemory

Inspiration

AI assistants are powerful, but most sessions still begin with amnesia. Applications either resend entire histories, bolt on a vector database, or hand user memory to an opaque hosted service. Coding agents have the same problem: they forget project conventions and prior decisions, while users cannot easily inspect or correct what was remembered.

GoodMemory started from a simple principle: durable memory should be a product layer of its own—local-first, explicit, auditable, and reversible.

What it does

GoodMemory gives AI products and coding agents a complete memory loop:

• remember selected facts, preferences, experiences, and project knowledge
• recall the most relevant context for the current task
• assemble an evidence-backed context pack for the next model turn
• inspect why memories were selected
• accept feedback, revise stale knowledge, forget individual memories, export data, or delete everything

It installs into Codex and Claude Code with goodmemory setup, lifecycle hooks, local SQLite storage, read-only MCP inspection, and opt-in writeback. Application developers can integrate through TypeScript, HTTP, Python, AI SDK, OpenAI Agents SDK, or any MCP-compatible client. An optional local Inspector provides categorized memory, candidate review, recall traces, revision/deletion controls, and audit events.

How we built it

The core is written in TypeScript and runs on Bun. SQLite is the zero-account local default, with PostgreSQL and custom storage adapters available for larger deployments.

The retrieval path combines generalized BM25, entity signals, reciprocal-rank fusion, temporal and relation-aware planning, with optional embeddings and provider reranking. Memory writing, recall, answer-context assembly, verification, maintenance, governance, and storage live behind explicit module boundaries.

The public API centers on remember, recall, buildContext, feedback, forget, exportMemory, and deleteAllMemory. Compiled packages, typed contracts, CLI setup flows, MCP, HTTP, and Python integration keep the same memory model across hosts.

Challenges we ran into

The hardest challenge was not storing more text—it was deciding what deserves to become durable memory, retrieving it without overfitting to benchmarks, and making every mutation governable.

We separated generalized production retrieval from historical benchmark-specific experiments, kept answer models and judges independent, and added strict public-claim gates so internal diagnostics cannot silently become marketing claims. We also had to preserve useful cross-session context without leaking current-session state or making deletion semantics ambiguous.

Accomplishments that we're proud of

• Published goodmemory@0.6.0 as an open-source npm package.
• A local-first install requires no account or hosted memory service.
• Codex and Claude Code can share the same governed memory model through hooks and MCP.
• The package exposes TypeScript, HTTP, Python, AI SDK, and standalone MCP integration paths.
• Current opt-in benchmark declarations are versioned, reproducible, and gated against overclaiming: LoCoMo, BEAM 100K, and MemoryAgentBench.
• Release verification covers thousands of tests, packed-consumer smokes, multiple Node versions, storage backends, and browser flows.

What we learned

Memory quality is as much a governance problem as a retrieval problem. A useful memory system must know what to save, show why it recalled something, preserve provenance, verify uncertainty, and make correction or deletion ordinary operations.

We also learned that evidence boundaries matter. A successful protocol run is not automatically proof of product uplift, and a judge score is not interchangeable with a deterministic result. GoodMemory keeps those distinctions visible.

What's next for GoodMemory

Next we are deepening Codex-native memory with controlled coding-effect evaluations, while keeping any coding-uplift claim blocked until the evidence is strong enough. We also plan to simplify installation across more MCP hosts, improve scenario-fitted recall without benchmark literals, expand the Inspector, and make governed team/project memory easier to deploy.

Built With

• bun
• codex
• mcp
• node.js
• openai
• postgresql
• python
• react
• sqlite
• typescript
• vite