GoodMemory

# GoodMemory

> Durable user/project memory layer for chat apps, copilots, and coding agents.
> Write selected facts, recall the right context, inject it into the next turn,
> audit what happened, and delete it when it is wrong.

GoodMemory is the product memory layer between an app or installed agent host
and the model runtime. It is **not** an LLM, an agent framework, a vector
database, or a generic RAG system. Local-first: Bun gets durable SQLite by
default and recall runs embedding-free out of the box; embedding providers,
Postgres, and LLM extraction are opt-in.

Release source: this source targets the GoodMemory 0.8.0 stable release.
Registry commands require goodmemory@0.8.0 to be published. The release workflow
verifies npm latest and the published GitHub assets against the locally prepared
manifest. It does not rebuild or publish.

If you are an autonomous agent reading this to decide whether to give *yourself*
memory: yes, that is a supported first-class path. Start with the decision tree
below. If you are here to *contribute to* GoodMemory instead, read AGENTS.md.

## Start here: onboarding decision tree

Pick the one path that matches how you run. Each is self-contained.

1. **You are, or run inside, Claude Code or Codex** → install the global CLI and
   let it wire the host:
   ```bash
   npm install -g goodmemory@0.8.0
   goodmemory setup        # detects Codex + Claude Code, installs managed wiring
   goodmemory status
   ```
   Not sure what is already installed? Run `goodmemory adopt` — it inspects the
   environment (`.claude/`, `.codex/`, existing MCP config) and prints the exact
   next command for your setup, or `goodmemory adopt --json` for a machine-
   readable plan.

2. **You speak the Model Context Protocol** (Cursor, Windsurf, Cline, Claude
   Desktop, Gemini CLI, OpenCode, or a custom MCP client) → add the standalone
   server; no `goodmemory setup`, no host config files:
   ```json
   {
     "mcpServers": {
       "goodmemory": {
         "command": "goodmemory-mcp",
         "args": ["--standalone", "--user-id", "YOUR_USER_ID"]
       }
     }
   }
   ```
   The two tools you need are `goodmemory_get_context` (recall) and
   `goodmemory_remember` (opt-in write via `--allow-write`); `goodmemory_write_note`
   (same opt-in) stores an authored page verbatim as a `note`; the other tools are
   diagnostic/advanced.

3. **You are a framework agent or a backend** (LangGraph, a custom loop, or a
   Python/other-language service) → call the HTTP bridge. Use the hosted
   instance `https://goodmemory.vibenest.net` (bring your own bearer token), or
   self-host in one switch:
   ```bash
   goodmemory-http-bridge --recommended   # local BM25 + entity + RRF; embeddings add an optional dense channel
   GOODMEMORY_PROFILE=agent-recommended goodmemory-http-bridge
   ```
   Python callers: `pip install goodmemory-client`. The recommended preset works
   without a provider; `GOODMEMORY_EMBEDDING_*` adds the dense channel.
   `GET /healthz` reports the active `retrievalTier` and `embeddingEnabled`.

After any local install, run `goodmemory inspector serve` to browse users and
scopes, review candidates, revise or delete memory, inspect recall evidence,
and audit mutations. The React console and `/admin/v1` API are loopback-only
and Bearer-token gated. See the
[Inspector and Admin API guide](https://github.com/hjqcan/GoodMemory/blob/main/docs/GoodMemory-Inspector-and-Admin-API.md).

## Memory API

- remember, recall, buildContext, feedback, forget, exportMemory, importMemory, deleteAllMemory

## Documentation

- [README](https://github.com/hjqcan/GoodMemory#readme): full prose, install paths, and the public benchmark table
- [Quickstart: Codex or Claude Code memory](https://github.com/hjqcan/GoodMemory#quickstart-codex-or-claude-code-memory)
- [Standalone MCP for any client](https://github.com/hjqcan/GoodMemory#standalone-mcp-for-any-client)
- [Python/FastAPI HTTP bridge](https://github.com/hjqcan/GoodMemory#pythonfastapi-http-bridge)
- [Inspector and Admin API](https://github.com/hjqcan/GoodMemory/blob/main/docs/GoodMemory-Inspector-and-Admin-API.md)
- [Memory Artifact and Interchange Spec](https://github.com/hjqcan/GoodMemory/blob/main/docs/GoodMemory-Memory-Artifact-and-Interchange-Spec.md)

## Benchmarks

Current `v0.8.0` claim: none. Versioned historical evidence: none.

The retained v0.7.3 LoCoMo and v0.6.0 LoCoMo, BEAM, and MemoryAgentBench
measurements, plus ImplicitMemBench, are internal diagnostics only. No end-to-end
benchmark runner is currently allowlisted, so current and historical promotion
both fail closed; stored-answer rescores and legacy projections cannot open it.
LongMemEval is withdrawn and
paused pending a clean label-free rerun. See the machine-readable declarations under
[benchmark-claims](https://github.com/hjqcan/GoodMemory/tree/main/benchmark-claims).

## Machine-readable

- [.well-known/goodmemory.json](https://github.com/hjqcan/GoodMemory/blob/main/.well-known/goodmemory.json): capability descriptor (install commands, MCP endpoint, HTTP endpoints, benchmarks) as JSON. A deployed bridge also serves it at `/.well-known/goodmemory.json`.