Pcnaid Memory OS
Get started

Thirty-two API families, one system of record

This is the index, not the brochure. Every route family the server exposes, what it is for, how many operations it has, and the page that explains it properly.

  • 141 documented paths
  • 18 MCP tools
  • 12 live memory layers
  • ≈55 Postgres tables
  • 25 operator pages

What the surface actually is

Five numbers, each one countable from the running service rather than from a slide.

141 paths
The OpenAPI document served at /openapi.json describes 141 paths. The live service reports 143; the two extra are the operator dashboard catch-alls, which are not API.
18 MCP tools
Exposed over stdio to any Model Context Protocol client, with a pcnaid_memory_usage prompt that teaches an agent when to call which. Shipped configs for Claude and the Codex CLI. See the tool list.
12 memory layers
Twelve layers are wired end to end and listed below. A thirteenth table exists in the schema with no readers or writers; it is not counted, and it is not sold.
≈55 tables
Across six Alembic revisions. Every tenant table carries tenant_id with row-level security enabled and forced. How the isolation works.
25 operator pages
A React dashboard over the same public API — memories, facts, sessions, Fabric, context, entities, media, knowledge base, eval, audit, PII vault, outbox, settings, billing, support, status and alerts.

Every route family, and where it is explained

Grouped by what you would be doing when you reach for it. Operation counts are from the shipped OpenAPI document, not from the older inventory files, which still describe a smaller tree.

Write and recall

The layers a running agent touches on every turn: what happened, what is true, what was decided, and what to send the model.

  • /v1/memory 10 operations. Create, list, search, edit, pin, archive and delete semantic and episodic records.
  • /v1/context 3 operations. Build a packed context block, return the retrieval plan behind it, or run a local retrieval benchmark.
  • /v1/chat 2 operations. Chat with retrieval and storage wired in, as a single response or a server-sent event stream.
  • /v1/facts 2 operations. Read the bitemporal fact store and override a fact, keeping what it replaced.
  • /v1/fabric 5 operations. Write, recall, list pending work, walk a project timeline and return a why-chain.
  • /v1/sessions 4 operations. Ingest an external transcript, summarise it into memory and search session messages.
  • /v1/kb 9 operations. Knowledge-base sources, documents, refresh scheduling, suggestions and settings.
  • /v1/media 3 operations. Transcribe a voice memo, ingest a multimodal item, summarise text into memory.
  • /v1/graph 2 operations. Query and rebuild the entity graph that sits beside vector and lexical search.
  • /v1/memory/entities … 8 operations across entities, observations, procedures and outcomes — the four structured memory types.

Higher-order memory

The cognitive tier. Eleven subsystems sharing one governance envelope: truth state, authority, review status, verification state and visibility on every record.

  • /v1/provenance 3 operations. Pin a claim to the span of source it came from and grade whether the source supports it.
  • /v1/memory-wiki 6 operations. Long-form articles over memory, with the WiCER review cycle attached.
  • /v1/memory-controls 4 operations. Named memory slots and six built-in retrieval recipes you can select per call.
  • /v1/architecture-memory 5 operations. Record how a system is actually built and scan a server-local path for drift.
  • /v1/memory-health 3 operations. Health scoring and dream reports over the memory a tenant has accumulated.
  • /v1/memory-exchange 3 operations. Import and export memory in six interchange formats.
  • /v1/explore-memory 6 operations. A browsable library over everything stored, for people rather than agents.
  • /v1/librarian 2 operations. Deterministic substring retrieval with citations — no model, no key, no latency.
  • /v1/default-mode 7 operations. The background runtime: consolidation passes, incubation and scenario templates.
  • /v1/agent-workflows 5 operations. An agent bus and a task graph, so several agents can share one memory and one plan.

Connect it up

How other systems reach the memory: events out, credentials in, keys for machines, and the billing surface behind the plans.

  • /v1/webhooks 2 operations. Register a subscription with an event-type list, then emit to matching targets with an HMAC signature.
  • /v1/integrations 4 operations. Per-tenant provider credentials, provider status, a summarisation smoke test and a token estimate.
  • /v1/api-keys 2 operations. Mint a scoped, hashed key shown once, then list or revoke it.
  • /v1/billing 4 operations. Stripe checkout, the customer portal, plan state and the webhook that keeps them in step.

Run it

The operator surface. Everything needed to keep the service up without buying a status page, a helpdesk or an alerting vendor.

  • /v1/admin 32 operations. Observability, audit, PII vault, the dead-letter outbox console, tenant settings, onboarding and GDPR export or delete.
  • /v1/support 3 operations. A tenant-scoped ticket desk with a staff queue, in the same database as everything else.
  • /status 3 operations. A public status page, a probe endpoint and a subscribable Atom incident feed.
  • /_/alerts/{severity} 1 operation. A token-authenticated alert receiver that opens tickets and pages the on-call user.
  • /metrics 1 operation. Prometheus exposition, admin-token protected.
  • /healthz /livez /readyz 4 operations including the service root. Liveness, readiness and a database round trip for the orchestrator.
  • /ui and /ui-legacy 3 operations serving the operator dashboard — 25 React pages over the same API you use.

The twelve layers underneath

A vector table stores one kind of thing. A memory operating system has to store several, because the questions people ask of it are not all the same question.

Layer Stored in What it answers
Semantic memories (mem_type=semantic) Durable facts, preferences and project knowledge.
Episodic memories (mem_type=episodic) Conversation turns, with the provenance of each.
Bitemporal facts facts What is true now, and what it replaced.
Fabric fabric_entries Decisions, tasks, reviews, outcomes, handoffs and evidence.
Sessions sessions, session_messages Imported transcripts and their rolling summaries.
Knowledge base kb_sources, kb_documents Refreshable external sources, quoted with citations.
Graph graph_facade.py Entities and their edges. Off by default; enable it deliberately.
Entity pcnaid_entities Clients, vendors, projects and policies as first-class records.
Observation pcnaid_observations Recurring patterns and signals worth keeping.
Procedural pcnaid_procedures How a given thing gets done here.
Outcome pcnaid_outcomes What worked, what failed, and what to try next.
Multimodal media_memory.py Voice, OCR and caption text, plus content fingerprints.

Every layer is reachable through POST /v1/context, which fuses them into one packed block with a source manifest attached.

One envelope over the higher-order tier

The eleven cognitive subsystems are not eleven separate products. Each record they write carries the same five governance dimensions, which is what makes them answerable together rather than eleven silos with eleven schemas.

The cognitive suite in full

truth_state
unknownfacthypothesissimulationsyntheticfiction
authority
rawgeneratedderivedhuman_reviewedlockedimported
review
draftneeds_reviewapprovedrejectedpromotedsupersededarchived
verification_state
unverifiedpendingsupportedpartially_supportedunsupportedcontradictedsuperseded
visibility
privatesharedorganizationpublished

Engineering notes on this map

The parts of the surface that are narrower than the route name suggests, or that need a decision from you before they do anything.

One family is not listed
/v1/experimental-retrieval (2 operations) is left off this map. It labels itself noncanonical, and its similarity metric expands a SHA-256 digest to bits, so the distance between two documents carries no meaning. We would rather say that here than sell it.
Supported, not switched on
Graph memory (ENABLE_GRAPH_MEMORY), knowledge-base retrieval (ENABLE_KB_RETRIEVAL), DiskANN indexing, cross-encoder reranking, the Postgres audit backend, OpenTelemetry and LLM entity extraction all default to off. They work; you turn them on knowingly.
The cognitive tier is file-backed
All twelve cognitive routers persist to a single append-only JSONL file today. Postgres tables for them exist in migration 0006 with no application readers or writers, so we do not describe that tier as RLS-isolated or horizontally scalable. The persistence model, stated plainly.
Deterministic where you would expect a model
The query planner, the temporal-intent detector, the default reranker, the librarian and claim verification are regex and heuristic code. That is why they run with no API key, no per-call cost and no provider latency — and why we never call them reasoning.

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