@ghostpaw/codex 0.3.2
When one agent saves a wrong fact, every agent trusts it.
codex keeps what your agent believes as beliefs with a source, a certainty and a history, so you can read and delete them one at a time instead of rereading MEMORY.md.
As a library
As a local MCP server
Follow one wrong fact Read the source on GitHub
Free, MIT licence, Node.js 24 or newer, zero runtime dependencies. One SQLite file on your machine.
0runtime dependencies
One wrong fact, five moves
The hard half is forgetting.
Here is one belief from the README example, from the guess that starts it to the call that deletes it. The cards show what codex 0.3.2 actually returned when we ran these calls on 2026-10-24 with a fixed clock, so the numbers are not made up for the page.
An agent saves a guess
One session guesses that the API still has a REST fallback and saves it. The belief is marked inferred, starts at 50% certainty and is flagged low trust before anyone has read it.
Belief #1 · fact
The API uses GraphQL with a REST fallback.
- source
- inferred
- certainty
- 50%
- evidence
- 1
- freshness
- 100%
low trust single evidence
write.remember(db, {
claim: 'The API uses GraphQL with a REST fallback.',
source: 'inferred',
category: 'fact',
});Another session finds it
A day later a different session asks about the API and gets the belief back with the flags still on it. That is the point: the second agent sees a guess, not a fact.
Recall is full-text search plus local similarity. No model is called.
Belief #1 · fact · recalled
The API uses GraphQL with a REST fallback.
- source
- inferred
- certainty
- 50%
- evidence
- 1
- freshness
- 99%
low trust single evidence
read.recall(db, 'graphql api');
read.listFlags(db);Someone checks and corrects it
Someone looks at the API and REST is gone. In a markdown file you would now have two lines that disagree. Here the old belief is marked superseded and drops out of recall, the new belief starts at 80% because it was observed, and the lineage keeps both.
Belief #1 · superseded by #2
The API uses GraphQL with a REST fallback.
Belief #2 · fact · supersedes #1
The API uses GraphQL exclusively; REST was retired.
- source
- observed
- certainty
- 80%
- evidence
- 1
- freshness
- 100%
single evidence
write.correctBelief(db, 1, {
claim: 'The API uses GraphQL exclusively; REST was retired.',
source: 'observed',
category: 'fact',
});Ninety days pass
Nobody confirms the belief for 90 days. Freshness is down to 37% and the belief is flagged stale, so it turns up in review instead of steering every run.
Confirm it and the clock starts over.
Belief #2 · fact · day 90
The API uses GraphQL exclusively; REST was retired.
- source
- observed
- certainty
- 80%
- evidence
- 1
- freshness
- 37%
stale single evidence
read.listFlags(db);
// stale, single_evidence
write.confirmBelief(db, 2);You retire it for good
Some things should not be remembered at all. Retire deletes the belief and its whole lineage: the call returns the deleted ids and recall comes back empty. Agents get the same call as the retire_belief tool.
Beliefs #1 and #2 · deleted
Nothing left to recall.
0 rows
write.deleteBelief(db, 2); // [1, 2]
read.recall(db, 'graphql api'); // []What one belief records
Each line your markdown file would hold becomes one row. Open the file with sqlite3 if you want to check.
- claim
- The sentence itself, kept short.
- source
- explicit, observed, distilled or inferred. Inferred and distilled beliefs are flagged low trust.
- category
- What kind of belief it is, such as a fact or a preference.
- certainty
- Starts from the source (explicit 90%, observed 80%, inferred 50%) and moves with confirmations.
- evidence
- How many times it was confirmed. One piece of evidence is its own flag.
- freshness
- Decays from the last confirmation; stale and fading flags are computed every time you read.
- lineage
- Which belief it superseded, with a before and after diff.
If memory makes your agent worse
Plenty of developers turn agent memory off. Unread memories pile up, and an old line wins against a new one. That is a fair reason, and most of codex exists because of it.
- Recall returns only active beliefs. Superseded and forgotten ones stay out of the prompt.
- Flags tell you what to prune: stale, fading, low trust, single evidence.
- Every write lists nearby beliefs, so a near-duplicate shows up when it is written, not months later.
- Retire deletes a belief and its history. Forget keeps the history but removes it from recall.
- The database is one local file. No server, no API key, no network.
What it costs to add
- Runtime dependencies
- 0
- Node.js
- 24 or newer (node:sqlite)
- Size of dist/index.js, gzip
- 31.5 KB
- Import time
- about 4 ms
- Tests
- 380 passing
- Agent tools
- 7
Measured 2026-10-24 on the maintainer's machine with Node.js 24.14.0 against codex 0.3.2: size of the published dist/index.js at gzip -9, median of 11 cold imports, tests from the v0.3.2 tag.
Start from the README
import { DatabaseSync } from 'node:sqlite';
import { initCodexTables, read, write } from '@ghostpaw/codex';
const db = new DatabaseSync('codex.db');
initCodexTables(db);
const { id } = write.remember(db, {
claim: 'The API uses GraphQL with a REST fallback.',
source: 'explicit',
category: 'fact',
});
write.confirmBelief(db, id);
read.recall(db, 'graphql api');
read.listFlags(db);The seven tools (search_codex, review_codex, inspect_codex_item, remember_belief, revise_belief, retire_belief, dismiss_proximity) ship with JSON Schemas for any LLM SDK. The MCP server and the command line tool use the same seven.