An engine that learns by admitting what it doesn't know.
Most AI memory systems are built to answer. Aporia is built to first notice when it can't — to mark the boundary of what it actually knows, hold there instead of bluffing, and then go acquire the missing piece through the cheapest trustworthy source. The honest "I don't know yet" is a first-class state here, not a failure: the system calls it holding aporia, and the things it doesn't yet know are tracked as plain gaps in a live queue called Open questions.
Lineage: Aporia's memory story starts with Open Brain (OB1) by Nate B Jones — the open-source unified-memory system this project ran on first. The fact store here grew out of daily use of his work, and its document layer was seeded from an Open Brain corpus. Credit to the original developer.
This repository is a blueprint, not a backup. It is written so that you — an AI with your own LLM, your own machine, and your own operator — can regenerate the Aporia Engine for your operator's needs, not restore this author's private instance. The system's data (personal facts, cart contents) is deliberately absent; the design and the builder code are what's here.
Read in this order:
- REPRODUCE.md — the environment (Postgres + pgvector, Ollama models, MCP registration) and the build order with per-component done-criteria.
- docs/design/ — the ratified design docs the components were built from; regenerate from these, not from the code alone.
- docs/ — the per-component guides:
newbrain.md,ladder.md,orchestrator.md,carts.md,verify.md.
And for how this came to be — the experimental arc from the original JEPA cartridge idea through the ideas that were tried and shelved — see docs/history.md. This repo is a backup, a blueprint, and the history of that experiment; the dead ends are kept on purpose.
Aporia is null-driven learning: everything hangs off honestly detecting the null — the gap or boundary in what's known — and then resolving it only as far as needed. Four owned components plus a verification layer:
The memory organ. Not a pile of text — a store of typed facts, each carrying a verdict (active / superseded / parked / contested), verbatim-quote evidence, and a temporal frame. Seven fact kinds (DECISION, RULE, STATE, PREFERENCE, REFERENCE, RESIDUAL, EVENT). A write runs a synchronous conflict-density check so a new fact that contradicts an existing one interrupts for resolution instead of silently coexisting. Retrieval labels every fact by verdict and age — an expired STATE serves as "last known," an EVENT never serves as a present-tense claim. See docs/newbrain.md.
When a lookup hits a gap, the ladder climbs only as far as it must to close it: L0 local
knowledge → L1 the owned corpus/carts → L2 external search (a subscription
claude -p + web-search subprocess, never a paid API without an explicit flag) → L3 ask
the human. The answering rung is recorded in provenance; low-trust leads become documents, not
facts. See docs/ladder.md.
The owned spine that dispatches work to models. It watches a queue of task records, routes each
by a roster (cheap models for mechanically-verifiable work, stronger models for judgment),
builds the prompt, runs mechanical gates on the result, and logs the outcome. Transport is
subscription-first; any use of a paid API path flags the human first. Workers never touch
main — branch per task, gates plus human review before merge. See
docs/orchestrator.md.
A cart is a domain knowledge pack the builder compiles from a source tree (code, docs) into embeddings + a fact contract the ladder can consult at L1. This repo ships the builder code so you can point it at your own source — the cart data is absent by policy (the reference carts embed licensed engine source and unreleased application code). See docs/carts.md.
The rift-verify / ue-verify MCP servers catch confident-wrong claims — statements that
are in-domain but false ("this method returns bool" when it returns a handle). Prose is
decomposed into typed, symbol-anchored facts; structural facts are checked as a pure index
lookup, behavioural ones routed to a local judge that may abstain rather than bluff. Abstains
become entries in Open questions — the same null-driven loop, pointed at code. See
docs/verify.md.
Three hardenings landed 2026-07-19 (patterns adopted from studying Graphify):
- Freshness (
index_cache.py,install_hooks.py,prewarm_cache.py) — parses are cached content-keyed, so rebuilds cost the diff, not the corpus; git hooks in the source clones touch a dirty marker and the server refreshes on its next call. A cart can no longer silently serve a stale index. - Confidence — every verdict carries
confidence+basis(extracted / inferred / ambiguous, discrete rubric inchecker.py): a parsed-index fact is not the same strength as a judge inference, and now the readout says so. - Call-graph (
CALLS:facts) — implementation bodies are brace-match parsed into a who-calls-whom index, so "X calls Y" / "X fires OnZ" claims get deterministic verdicts (direct = extracted; one hop = inferred; absent = flag) instead of judge round-trips.
| term | meaning |
|---|---|
| gap | something the system doesn't yet know — a detected null |
| holding aporia | the honest-abstain state: declining to guess when the answer is a gap |
| Open questions | the live queue of gaps awaiting acquisition or a human answer |
Every answer is yes / no / or null, and null — "not yet known" — is a legitimate state, never collapsed into whichever answer keeps momentum. A null is triaged, not reflexively resolved: cheap-and-high-risk gaps get closed now, low-risk ones ship as known/expected items in Open questions. Verification is asymmetric — refuting a claim is cheaper and safer than confirming one, so the system leans toward "not yet confirmed" over a hopeful yes.
The fact store, ladder, orchestrator, verification layer, and cart builder are built and in
use. This is a working system under active development, not a finished product; the design docs
in docs/design/ are the source of truth for intended behaviour where code and prose disagree.
Footnote. The name Aporia is the classical term for the honest impasse — the point of holding an I don't know. Its knowledge-gap cousin term, lacuna, names the idea the whole system is built around; operationally, though, the code and docs use the plain word gap and the queue name Open questions. This footnote is the only place that word appears.