Pcnaid Memory OS
Get started

It knows the difference between a fact and a guess

The cognitive tier is where Memory OS stops treating everything an agent writes as equally true. Every record carries five governance dimensions, and the system refuses to let a simulation, a hypothesis and a verified fact blur into one another.

  • 5 governance dimensions
  • 10 API families
  • 44 API paths
  • Runs with no API key

The governance envelope

Most memory systems store a string and a timestamp. Every record here also states what kind of thing it is, where it got its standing, whether a human has looked at it, whether evidence backs it, and how far it is allowed to travel.

Every record in the cognitive tier carries all five dimensions, always. A simulation cannot quietly become a fact, because the state it is in is a stored field with a fixed vocabulary — not a convention, a prefix or a tag somebody remembered to add.
truth_state
unknown · fact · hypothesis · simulation · synthetic · fiction. What kind of thing this is. A record written by the reflection runtime starts as a hypothesis; one produced by a future simulation is stamped simulation and can never be read as anything else. Defaults to unknown.
authority
raw · generated · derived · human_reviewed · locked · imported. Where it got its standing. A quoted source span is raw. A compiled page is derived. Anything arriving from another system is imported, which is a deliberately weak claim. Defaults to generated.
status
draft · needs_review · approved · rejected · promoted · superseded · archived. Where it is in the human loop. Promotion is a separate, explicit step, so nothing reaches approved by accident. Defaults to draft.
verification_state
unverified · pending · supported · partially_supported · unsupported · contradicted · superseded. Whether evidence actually backs it. This is set by the claim checker, not by whoever wrote the record. Defaults to unverified.
visibility
private · shared · organization · published. How far it may travel. Publishing is opt-in per record, and the Explore Memory publication manifest lists exactly what is published. Defaults to private.

The failure this prevents

An agent brainstorms five possible futures for a project. Two weeks later something retrieves one of them and presents it as what the team decided. Nobody lied; the store simply had no way to say that one of those sentences was invented and the other was recorded.

Here the invented one is written with truth_state: simulation and synthetic: true, and that flag is set automatically whenever the truth state is simulation or synthetic — it is not left to the caller to remember. Listing records defaults to including them, but the Librarian's include_synthetic defaults to off, so ordinary questions never see them.

The same refusal runs through the rest of the tier. The reflection critic forces anything risky or unevidenced to needs_review. Every imported record lands with authority: imported and, unless you explicitly opt out, status: needs_review — never silently trusted. A claim's verification state is written by the checker that graded it, not by the process that wrote the claim.

How the Librarian labels uncertainty

Deterministic where it counts

Several of these subsystems do their work with no model behind them at all. That is a design choice, and it is worth being blunt about what it does and does not buy you.

What it costs

Nothing. No API key, no per-call spend, no provider round trip and no added latency. A self-hosted deployment with no credentials configured gets the whole tier working, not a degraded version of it.

What it guarantees

The same input produces the same output twice. A verification result can be recomputed and checked by anyone holding the same evidence, which is what makes an audit trail worth keeping.

What it is not

It is not reasoning. Claim grading is lexical overlap, not semantic entailment. The Librarian retrieves and cites; it does not synthesise. Three of the Default Mode endpoints return fixed checklists. Each page below says exactly which is which.

Engineering note: how this tier is stored

This matters enough to say plainly rather than bury in a footnote, because it decides whether the tier fits your deployment.

The cognitive routers do not write to Postgres. All of them persist through one module — backend/app/cognitive/repository.py — into a single append-only JSONL file, pcnaid_cognitive_records.jsonl, under the configured data directory. Creates append a line. Updates and archives rewrite the whole file atomically through a temporary file and a rename, so a crash mid-write cannot leave a half-file behind.

Migration 0006_cognitive_integrations does create twelve Postgres tables for this tier, and they carry the same shape. Today nothing in the application reads from or writes to them. We are not going to describe this tier as Postgres-backed, row-level-security isolated or horizontally scalable, because it is none of those three.

What it is: fast, dependency-free, trivially inspectable with grep, and correct on a single node. Records are filtered by tenant on every read, but that filter is application code, not a database policy. If you run several API replicas, run this tier on one of them.

The twelve memory layers underneath — semantic, episodic, bitemporal facts, Fabric, sessions, knowledge base, entities and the rest — are a different story entirely. Those are Postgres, with FORCE ROW LEVEL SECURITY on every tenant table and a runtime role that CI asserts is neither owner, superuser nor BYPASSRLS.

How tenancy is enforced in the core

PropertyCognitive tierCore memory layers
Store One append-only JSONL file Postgres
Tenant isolation Application filter on read FORCE ROW LEVEL SECURITY
Multi-replica Single node Yes
Backup Copy the file Standard Postgres tooling
Schema Normalised on read Migrated, typed columns

Migration 0006 ships twelve tables for this tier. They exist; no application code reads or writes them yet.

Ten API families

Forty-four paths, grouped by the job they do. Each links to the page that covers it in full.

Prove it

Where a claim came from, and whether the evidence actually says so.

  • /v1/provenance Source spans with character, line and page offsets and a SHA-256 quote hash; claim grading; an evidence-coverage report. Three paths.
  • /v1/memory-wiki Compile records into Markdown pages with slugs, content hashes and full input lineage, then check whether compression lost facts. Six paths.

Control it

The context an agent should never have to rediscover.

  • /v1/memory-controls Typed always-on slots with confidence, evidence and a lock that refuses deletion, plus six named retrieval recipes. Four paths.
  • /v1/architecture-memory Import an architecture contract or scan a server-local tree, flag duplicate responsibilities, and brief a coding agent before it edits. Five paths.

Coordinate it

Several agents, one shared record of what is happening.

  • /v1/agent-workflows An append-only message bus and a dependency-aware task graph with time-boxed leases. Five paths.
  • /v1/default-mode A bounded background runtime that reflects, consolidates and criticises — and only ever writes candidates. Seven paths.

Maintain it

What state the memory is in, and how it gets in and out.

  • /v1/memory-health A weighted 0–1 health score with a full breakdown, a Markdown maintenance report and the human review queue. Three paths.
  • /v1/memory-exchange Six export formats, and an import path that stages everything as needs_review rather than trusting it. Three paths.
  • /v1/explore-memory Projects records onto a six-level taxonomy — Network, Hub, Node, Track, Surface, Leaf — with browse, graph, timeline and a publication manifest. Six paths.
  • /v1/librarian Retrieval over that library with citations and an explicit uncertainty label, plus “why do we know this?” for any record. Two paths.

Keep reading

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.

Get started Read the API docs