GoodMemory

# GoodMemory

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

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

> **Release source:** this is the immutable `0.7.5` stable release source.
> Registry commands require `goodmemory@0.7.5` to be published. The release
> workflow verifies npm `latest` and artifact integrity before creating the
> GitHub Release.

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.

## 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](https://github.com/hjqcan/GoodMemory/compare/373e1f9a...5d7639a8)
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.** Install the published `0.7.5` registry baseline and inspect
its local memory surface:

```bash
npm install -g goodmemory@0.7.5
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](https://devpost.com/software/goodmemory) and
[public demo video](https://youtu.be/xK663ultN5o).

**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

```bash
npm install -g goodmemory@0.7.5
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). 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.7.5` 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.

<!-- current-claims-table:start -->
No benchmark result is currently presented as measured on `0.7.5`.
<!-- current-claims-table:end -->

### Versioned evidence

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

<!-- historical-evidence-table:start -->
No benchmark result currently qualifies as versioned historical evidence.
<!-- historical-evidence-table:end -->

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](./benchmark-claims/longmemeval.json).
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](./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