Memory rots unless somebody looks at it
Records pile up unverified, drafts never get reviewed, contradictions sit unresolved and nobody notices until an answer is wrong. This page is the maintenance layer — a score you can watch, a report that says what to fix, portable import and export, and a librarian that cites what it found.
- 0–1 weighted health score
- 6 export formats
- 14 endpoints
- Simulations excluded by default
One number, and every input to it
A health score is only worth having if you can take it apart. This one is a fixed weighted sum of four measured ratios, and the endpoint returns all four alongside it.
GET /v1/memory-health returns the score and every input to it —
counts by kind, status and verification state, the evidence reference count,
the average confidence and the two pressures. The arithmetic is fixed, so
the same corpus always produces the same number and a change in the score
always has a cause you can point at.
Evidence coverage is the share of records that came back supported or partially supported — the proportion of your memory that has actually been checked against something. Average confidence is the mean across every record. Between them they carry 70% of the score, which is deliberate: the two questions that matter most are whether it is backed and how sure it is.
Review pressure is the share sitting at draft or needs_review — the backlog nobody has looked at. It enters the score inverted, so a growing queue drags the number down. Contradiction pressure is the share explicitly contradicted; it carries the smallest weight because it is usually small and always urgent.
The response also breaks the corpus down by kind, by status and by verification state, and reports the total evidence-reference count, the synthetic count and how many records are unsupported or contradicted. When the score moves, those counts tell you which term moved it.
# Memory Dream Report
Health score: 0.73
Total records: 1,284
Evidence coverage: 0.62
Review pressure: 0.18
## Suggested next actions
- Evidence coverage is low; run Provable
Memory verification for compiled claims
- Synthetic simulations are present; keep
them out of default task retrieval
// persisted as a record unless persist=false
The report writes itself as Markdown with the score, the totals and a
prioritised action list. Suggestions appear on thresholds rather than
vibes: review pressure above 0.25, evidence coverage below 0.5, any
unsupported or contradicted record at all, any synthetic record at all.
With nothing to raise, it says so.
GET /v1/memory-health/review-queue is the worklist that
follows — everything at needs_review, newest first, which is
what a person actually opens on a Monday.
Memory you can take with you
Memory that cannot leave the system that holds it is a hostage situation. Six export formats, and an import path that refuses to trust anything on arrival.
| format | What you get |
|---|---|
okf | The default. A manifest plus every record, whole — the shape to hand another Memory OS. |
jsonl | One record per line. The shape to stream, grep or feed to a pipeline. |
markdown | A section per record with kind, status and verification state in the header. For people. |
jsonld | A @graph under a pcnaid namespace, carrying status and verification state as typed properties. |
graphml | Nodes as XML, for a graph tool that already reads GraphML. |
llms_txt | Title, kind, status and the first 1,200 characters of each record. For a context window. |
Every export carries a manifest naming the format, the record count
and a canonical source of
pcnaid-memory-os:cognitive_records — plus
review_required_on_import: true, which is the bundle
telling the next system how to treat it.
Import is staging, not merging
Every record in an incoming bundle is written as a
staged_import with authority
imported, verification state
unverified and status needs_review. It is
not in your memory yet. Nothing that arrived from elsewhere gets
to inherit the standing of something you verified yourself.
POST /promote/{record_id} accepts one staged
record and writes the real one, keeping the staged row as its
evidence reference and marking it promoted with a pointer to what
it became. The trail from “someone sent us this” to “we now rely
on it” stays intact.
Bundles can arrive as a parsed object, a JSON string or
newline-delimited JSON, and a bare record is accepted as a bundle
of one. There is an auto_approve flag for a migration
you genuinely trust — it defaults to off, and it should stay off
for anything you did not export yourself.
A library, not a bucket
/v1/explore-memory projects records onto six levels, so a
corpus that has grown past the point of browsing becomes navigable
without anybody filing anything by hand.
| Level | What it holds, and how it is derived |
|---|---|
Network | The whole library. Defaults to “Memory OS”; name your own to keep several apart. |
Hub | The subsystem a record came from — Provenance, Compiled Knowledge, Architecture Memory, Default Mode, Agent Workflows, or Memory Library for everything else. |
Node | The project the record belongs to, falling back to its kind when it has no project. |
Track | Synthetic when the record is a simulation, Reviewed when a person has signed it off, Agent otherwise. Three tracks, and you can always tell which you are reading. |
Surface | What kind of thing it is, in library terms: Pages, Claims, Evidence, Pinned Context, Reflections, Simulations. |
Leaf | The record itself, titled. |
Placement is automatic and overridable. POST /project
derives the hub from the record's kind, the track from whether it
is synthetic or human-reviewed, and the surface from a small fixed
map — but every level is a parameter, so you can file something
exactly where you want it. POST /rebuild re-projects
the whole corpus and skips anything already projected.
The Track level is the one worth pausing on. Everything synthetic lands on the Synthetic track, everything a person approved lands on Reviewed, and everything else lands on Agent. Browsing one track at a time means you can read only the reviewed material, or audit only what the agents produced, without filtering by hand.
-
browse
Filter by any level, or search across them. Returns both the flat item list and the nested tree, so a sidebar and a result list come from one call.
-
graph
The same items as nodes, with a derived_from edge back to the source record and an evidenced_by edge for every evidence reference it carries.
-
timeline
The same items ordered by when they last changed, with their status and verification state — what moved, and in what order.
-
publication-manifest
Exactly what is visible at a given level, defaulting to published, as navigation entries. The answer to “what have we actually made public?”, on demand.
The Librarian answers with evidence, not prose
POST /v1/librarian/ask is retrieval with citations and an
explicit uncertainty label. There is no model behind it and no
synthesis step, and that is worth being exact about.
A question is matched as a substring across each record's title, text, payload and tags. The matches come back as citations — record id, title, kind, verification state, evidence references and whether the record is synthetic — each with its opening text. Nothing is rewritten, summarised or paraphrased, so nothing can be introduced that was not already in a record.
That is a narrower promise than “ask an AI librarian”, and it is a more useful one for the job this does. It costs nothing, needs no key, adds no latency, returns the same result twice, and cannot invent a citation — because it never writes a sentence in the first place. When you want a model's words, you pass these citations to your own model with your own prompt, and the evidence is already assembled.
include_synthetic defaults to false,
so simulations are excluded from ordinary answers unless you ask
for them by name. require_verified narrows further to
records that came back supported or partially supported.
project_id scopes it, and limit caps the
citation count at up to 50.
"question": "grace period"
uncertainty mixed_verification
citations
compiled_page topic/grace-period
partially_supported
source_span doc_4471
supported · 1 evidence ref
// include_synthetic: false by default
// nothing is rewritten — these are the
// records themselves, with their state
grounded_synthesis
Every citation returned is supported or partially supported. The evidence behind this answer has been checked.
mixed_verification
At least one citation is unverified or worse. The answer is real, but not all of it has been stood up.
no_match
Nothing matched in scope, and it says so in plain words rather than producing something that sounds like an answer.
GET /v1/librarian/explain/{record_id} answers the
other question: why do we know this? It returns the record, its
authority, verification state and confidence, its source and evidence
references resolved into the actual records behind them, and the related
records that mention the same thing.
Fourteen endpoints
Four API families, one job between them: keep the memory worth trusting.
| Endpoint | What it does |
|---|---|
GET /v1/memory-health | The score and every input to it, with counts by kind, status and verification state. |
POST /v1/memory-health/dream-report | A Markdown maintenance report with prioritised next actions. Persisted as a record unless you ask it not to be. |
GET /v1/memory-health/review-queue | Everything sitting at needs_review, newest first. Up to 1,000. |
POST /v1/memory-exchange/export | Export in one of six formats, filtered by kind or by query, up to 10,000 records. |
POST /v1/memory-exchange/import | Stage a bundle. Accepts an object, a JSON string or newline-delimited JSON. |
POST /v1/memory-exchange/promote/{record_id} | Accept one staged record into real memory, keeping the staged row as its evidence. |
POST /v1/explore-memory/project | Place one record on the taxonomy, deriving hub, track and surface unless you set them. |
POST /v1/explore-memory/rebuild | Re-project the whole corpus, skipping anything already projected. |
GET /v1/explore-memory/browse | Filter by any level and get both the flat list and the nested tree. |
GET /v1/explore-memory/graph | Items as nodes, with derived_from and evidenced_by edges. |
GET /v1/explore-memory/timeline | The same items ordered by when they last changed. |
GET /v1/explore-memory/publication-manifest | Exactly what is published, as navigation entries. Pass a different visibility to audit any tier. |
POST /v1/librarian/ask | Retrieve matching records with citations and an uncertainty label. Simulations excluded unless asked for. |
GET /v1/librarian/explain/{record_id} | Why this is known: authority, verification state, confidence, source references, resolved evidence and related records. |
Give your agents a memory you can audit
Run the whole system on your own hardware under the MIT licence, or ask us about hosted access. Both start from the same place.