agidb — Project Guide (v2)

The single-document reference for agidb v2: what it is, why it exists, what’s built today (inheriting from sochdb v1), the full architecture, the v2.0 substrate plan (9 months), the v2.1 brain-alignment milestone (12 months), and the complete 5-year roadmap toward AGI-grade infrastructure. If you read one file, read this one.

Last updated: 2026-05-20 · Status: v2.0 pre-alpha · Inherits from: sochdb v1 (phases 0, 1, 2, 4, 6 complete)

Table of contents

1. What agidb is
2. Why agidb exists
3. The pivot from sochdb v1 to agidb v2
4. Where we are right now
5. Architecture
6. The data model
7. The build roadmap
8. Brain-alignment in v2.1+
9. Feature catalogue
10. Tech stack
11. The decision gate
12. The 5-year trajectory
13. How to navigate the project

1. What agidb is

agidb is the cognitive substrate for autonomous AI agents — content-addressable hyperdimensional memory, first-class goals and beliefs, bi-temporal supersession, sleep-like consolidation, and a non-destructive unlearn primitive. One Rust binary, one API, no query language. The database AGI systems will run on top of.

It is a new category of database. Not a vector database, not a graph database, not a key-value store. It is built for a consumer no existing database was designed for: an autonomous AI agent that needs to remember, reason, revise, and forget over months and years.

let db = Agidb::open("./memory.agidb").await?;

db.observe("Sarah recommended Bawri in Bandra last weekend").await?;
db.assert_belief(Belief::new("Sarah likes thai food").with_confidence(0.8)).await?;
db.set_goal(Goal::new("find a thai place for the team dinner")).await?;

let result = db.recall("what thai place did sarah mention?").await?;
// → Bawri, confidence 0.94, with provenance back to the original observation,
//   goal-biased because "find a thai place" is currently active.

No SQL. No Cypher. No embedding API calls. No separate vector DB. No rerank step. One function.

The wedge

agidb integrates binding and recall without an external index — storage and retrieval share the same representation. And on top of that substrate, it adds the four primitives no other database has: first-class goals, revisable beliefs, sensory buffering, and non-destructive unlearn. These five things together are the wedge.

v2.1 adds a sixth differentiator: brain-aligned multimodal sensory encoding. Same encoder stack as Meta FAIR’s TRIBE v2 (V-JEPA 2 video, Wav2Vec-BERT audio, Llama-3.2-3B text). Surprise threshold calibrated against neural surprise signals from 720-subject fMRI ground truth. This makes agidb the first agent memory substrate with publishable cortical alignment.

Who it’s for

• Developers building autonomous AI agents currently fighting with mem0, Letta, Zep, Cognee, LangMem, or a hand-rolled vector-DB-plus-graph stack — who need not just memory but typed cognition, with full provenance and audit.
• Teams building toward AGI — frontier-adjacent startups and research groups who need a substrate where goals, beliefs, and self-model are first-class, not bolted on.
• Developers in regulated industries — healthcare, legal, finance — who need auditable memory, non-destructive updates, and a non-destructive unlearn API to handle right-to-be-forgotten.
• Developers building local-first / offline-first AI — coding agents, desktop assistants, on-device personal AIs — who can’t depend on cloud services.
• Cognitive science researchers (v2.1+) — who want to benchmark agent memory architectures against human cortical ground truth via BAMS.

Who it’s not for

A general-purpose database, a full-text search engine, a pure vector-similarity store, a hosted-only service, a multimodal-document store, a distributed database, or a knowledge-graph editor with a UI. Use the right tool for those, then put agidb on top.

2. Why agidb exists

Every existing database was designed for a different consumer: postgres for accountants, mongodb for app developers, neo4j for analysts, pinecone/qdrant for retrieval pipelines, mem0/letta/zep for chat-style RAG memory. None were designed for an autonomous agent that needs to remember, reason, revise, and forget over time with full provenance and audit.

The standard agent-memory pattern today is a six-step pipeline: embed every conversation → store vectors → embed the query → similarity search → rerank with another LLM call → stuff chunks into the prompt. This pipeline has six structural problems:

And on top of those, four problems specific to autonomous agents:

These aren’t bugs — they’re properties of the wrong primitive. agidb is the right primitive.

The three foundations

1. Content-addressable storage — memories are high-dimensional binary signatures; retrieval is bit-overlap counting, not query parsing. (How the hippocampus works.)
2. Bi-temporal supersession — new facts don’t overwrite old ones; they supersede, and you can query the DB “as of” any historical date. (How legal/financial systems — and human memory — track changing facts.)
3. Sleep-like consolidation — a surprise-gated background worker compacts repeated episodic patterns into semantic concepts, decays unused memory, flags contradictions. (The McClelland-McNaughton-O’Reilly complementary-learning-systems model, extended with surprise gradients.)

The four extensions that make it AGI-grade

4. Goals as first-class typed shapes — state machines with parent-child structure, success criteria, deadlines. First database to ship this.
5. Beliefs with explicit revision — confidence-tracked claims with audit trails of every revision. The agent can prove what it believed, when, and why.
6. Sensory buffer with surprise gating — a short-lived ring buffer of recent input, promoted to episodic memory only when surprise exceeds threshold.
7. Non-destructive unlearn API — cascading removal of facts with full audit trail. Right-to-be-forgotten as a first-class operation.

The brain-aligned extension (v2.1)

8. Multimodal sensory encoding via TRIBE-aligned encoders. V-JEPA 2 for video, Wav2Vec-BERT for audio, Llama-3.2-3B for text. Each modality projected to 8192-bit HDC signatures via thresholded random projection (Charikar 2002). Episode signatures fused via VSA role-filler binding — factorable, unlike attention-based fusion.
9. Brain-calibrated surprise gating. Surprise threshold empirically fit against neural surprise predicted by TRIBE v2 on 720-subject fMRI. Replaces the magic threshold from v2.0 with measurement-grounded calibration.
10. BAMS — the brain-aligned memory similarity benchmark. Six-cortical-network RSA evaluation against TRIBE v2 ground truth. First brain-alignment benchmark for agent memory. Paper to ICLR 2026 MemAgents.

Why now

1. Agent memory became a category — Mem0 ($24M Series A, October 2025), Letta ($10M seed, September 2024), Cognee ($7.5M seed February 2026), Zep — all real funding, no AGI substrate yet.
2. HDC/VSA research matured for production — Torchhd (2023), karunaratne et al. nature electronics 2020, PathHD, HPE Hippocampus papers showing binary-signature retrieval beating vector DBs by 31× latency and 14× token cost.
3. The embedded-DB category got serious in Rust — duckdb, lancedb, redb, surrealdb, tigerbeetle all matured.
4. Frontier labs are not building externalizable substrates. Anthropic’s September 2025 memory tool is a file-directory CRUD API. OpenAI’s April 2025 ChatGPT memory upgrade is a product feature. Google’s Gemini Personal Context is a product feature. The open vendor-neutral substrate wedge is empirically unoccupied.
5. NEW: Brain-encoding foundation models matured (March 2026) — Meta TRIBE v2 released open weights for a foundation model predicting fMRI BOLD across 720 subjects from V-JEPA 2 + Wav2Vec-BERT + Llama-3.2-3B. This makes brain-aligned evaluation tractable for the first time. agidb v2.1 is built on the same encoder stack to inherit alignment.

3. The pivot from sochdb v1 to agidb v2

agidb v2 is the v2 successor to sochdb v1. every line of sochdb’s code carries forward. the HDC math is the same. the storage layout is the same. bi-temporal supersession is the same. agidb is sochdb extended with the cognitive primitives an AGI substrate requires.

If you used sochdb v1, agidb v2 is a strict superset. No migrations required for the substrate features you already use; new tables and types are additive.

What carries forward unchanged

• The HDC kernel. bind, bundle, hamming, AVX-512/NEON/portable POPCOUNT paths. perfect as-is.
• The redb + mmap storage layer. the on-disk format works for everything we’d add. just more tables.
• Bi-temporal supersession. central to agidb, already shipped in v1.
• Episode encoding and signature math. the binding for episodic memory works identically for semantic atoms and beliefs.
• The four-tier recall cascade. tier A/B/C/D works for any memory type.
• Consolidation clustering and contradiction detection. the math is correct for all the floors that need it.
• The constitution and design discipline. test-first, red-green rhythm, no-LLM-in-read-path, never-return-empty — all preserved.

What extends naturally (adds rather than changes)

• Floor 6: goals and beliefs as first-class types. New Goal and Belief types in agidb-core::types. New redb tables. New API methods.
• Floor 1: sensory buffer with surprise gating. Lightweight ring buffer in redb. New API surface for raw observations before episodic promotion.
• Floor 7: self-model and learning log. Extension of the existing consolidation_log into a general learning_events log. New introspection methods.
• Unlearn API. Cascading non-destructive removal with audit log. Brand new but uses existing supersession primitives.
• Neurosymbolic interface. Explicit translation between HDC signatures and structured triples/beliefs. Already implicit; makes the seam first-class.

What gets added in v2.1 (brain-alignment)

• Multimodal sensory encoders. New agidb-sensory crate. V-JEPA 2, Wav2Vec-BERT, Llama-3.2-3B as feature extractors. ONNX/Candle backends.
• HDC projection layer. Charikar 2002 thresholded random projection from dense latents (1024d, 2048d) to 8192-bit signatures. Deterministic, seed-fixed.
• Brain-calibrated surprise threshold. Calibration tooling against TRIBE v2 fMRI predictions.
• BAMS benchmark suite. New agidb-bams crate. RSA evaluation against TRIBE-derived cortical ground truth.

What gets reconsidered

What does not change

The wedge. Content-addressable HDC retrieval, bi-temporal supersession, embedded Rust binary, no LLM in read path, never return empty, full provenance. These are still the differentiators against mem0/zep/letta/cognee. The AGI pivot adds cognitive primitives on top of this foundation — it doesn’t replace the foundation. Brain-alignment in v2.1 is additive on top of the cognitive primitives — it doesn’t replace them either.

4. Where we are right now

agidb v2 inherits sochdb v1’s five completed phases. v2.0 needs five new phases for the AGI substrate (phases 9-13). v2.1 adds three more phases for brain-alignment (phases 14-16). Total: 8 phases of substrate work (carrying forward from sochdb) + 5 new phases of cognitive primitives + 3 new phases of brain-alignment = 16 phases.

Phase completion (carried forward from sochdb v1)

New phases for the AGI pivot (v2.0)

New phases for the brain-alignment milestone (v2.1)

What’s built in agidb-core today (inherited from sochdb v1)

The engine crate is real, tested code. Other crates are scaffolded stubs.

What gets added in agidb-core for v2.0

What gets added for v2.1

Test status (inherited)

44 tests passing, 1 ignored (cargo test -p agidb-core):

• 3 — types unit tests
• 13 — hdc_properties — HDC algebra invariants
• 9 — storage_properties — round-trips, supersession (1 ignored: alias resolution, phase 3)
• 11 — recall_properties — tier A/C/D, fall-through, as_of
• 8 — consolidate_properties — clustering, atom creation, contradictions

Plus a criterion benchmark (hdc_scan): 8192-bit hamming scan over 100k signatures — ~5.4ms on a Zen 4 laptop (portable path; M2 NEON path is the official target).

What you can do with the engine today

observe a pre-extracted episode (text + triples) → it’s signed, indexed, and bi-temporally stamped. recall a cue → tier-A exact concept lookup, tier-C gist similarity, tier-D nearest-neighbor fallback (recall never returns empty). consolidate → repeated episodes cluster into semantic atoms, contradictions get superseded. supersede, export_jsonl, import_jsonl all work.

What’s not built yet

• Raw-text extraction (phase 3) — blocks tier B and alias resolution
• MCP server + Python bindings (phase 5)
• Cognitive primitives (phase 9) — goals, beliefs
• Sensory buffer + self-model (phase 10)
• Unlearn API (phase 11)
• Neurosymbolic interface (phase 12)
• Benchmark harnesses (phases 7 and 13)
• Multimodal sensory encoders (phase 14) — V-JEPA 2, Wav2Vec-BERT
• Brain-calibrated surprise (phase 15)
• BAMS suite (phase 16)
• Decay + compaction in consolidation
• Background consolidation scheduler

5. Architecture

agidb is built in three engineering layers that implement seven cognitive floors. The user only ever interacts with the floors via the public API; the engineering layers are invisible.

The three engineering layers

┌──────────────────────────────────────────────────────────────┐
│  LAYER 1 — RECALL                                            │
│  The mind-like layer. HDC signatures, binding, bundling,     │
│  hamming-distance retrieval, tiered confidence, goal-biased  │
│  weighting. This is what the user experiences.               │
└──────────────────────────────────────────────────────────────┘
                              ▲
┌──────────────────────────────────────────────────────────────┐
│  LAYER 2 — EXTRACTION                                        │
│  The scaffolding. v2.0: GLiNER ONNX entity/relation          │
│  extraction, belief extraction, time-anchor parsing.         │
│  v2.1: V-JEPA 2 (video), Wav2Vec-BERT (audio),               │
│  Llama-3.2-3B (text). All project to 8192-bit HV.            │
└──────────────────────────────────────────────────────────────┘
                              ▲
┌──────────────────────────────────────────────────────────────┐
│  LAYER 3 — STORAGE                                           │
│  The plumbing. redb for metadata + bi-temporal indexes.      │
│  mmap'd flat files for signatures. Append-only logs for the  │
│  self-model audit trail. Crash-safe, ACID, Rust.             │
└──────────────────────────────────────────────────────────────┘

The seven cognitive floors

The biological mapping. These are what the user experiences and what agidb stores. The three engineering layers above are how it’s built.

Why three layers and not one

A biological brain stores memories as activation patterns in cortical neurons — extraction is implicit in perception, and synaptic weights are the storage. We don’t have 86 billion neurons on a laptop, so we simulate brain-like behaviour with conventional parts: layer 1 simulates retrieval-by-overlap, layer 2 prepares input so signatures are robust to phrasing, layer 3 persists reliably with crash safety. The user gets brain-like behavior; the engineering does the work.

Why seven floors and not three

The three engineering layers tell you how agidb is built. The seven cognitive floors tell you what it stores and what shapes the API takes. Three is a system-design abstraction; seven is a cognitive-science abstraction grounded in 50 years of memory research (Tulving, Squire, Baddeley, McClelland). Both are required to understand the system fully.

The write path — observe() (v2.0)

USER  db.observe("Sarah recommended Bawri in Bandra last weekend")
  │
  ▼  FLOOR 1 — SENSORY BUFFER (lightweight)
  │  1. record raw text in sensory ring buffer with timestamp
  │  2. compute surprise score against current beliefs
  │  3. if surprise > threshold OR explicit observe() call: promote
  │
  ▼  LAYER 2 — EXTRACTION
  │  1. GLiNER ONNX (~150ms CPU) extracts entities + relations
  │  2. resolve "last weekend" → 2026-05-09 (valid time)
  │  3. attach confidence scores; canonicalize entity names
  │  4. optionally extract beliefs (high-confidence claims)
  │
  ▼  LAYER 1 — BINDING
  │  1. look up / assign 8192-bit HVs per concept
  │  2. bind triples into role-filler patterns:
  │     triple = (SUBJ⊗Sarah) ⊕ (PRED⊗recommended) ⊕ (OBJ⊗Bawri)
  │  3. bundle triples into one episode signature
  │  4. also compute a raw-text gist signature
  │
  ▼  LAYER 3 — STORAGE
  │  1. append 1KB signature to signatures.dat
  │  2. write episode row to redb (text, offset, triples,
  │     bi-temporal stamps, provenance, confidence)
  │  3. update inverted index + concept index
  │  4. emit LearningEvent::EpisodeStored to floor 7 log
  │  5. fsync, return EpisodeId
  │
  ▼
USER gets EpisodeId

The write path — observe_multimodal() (v2.1)

USER  db.observe_multimodal(video_clip, audio_clip, "sarah said bawri")
  │
  ▼  FLOOR 1 — SENSORY BUFFER (multimodal)
  │  1. record raw modalities in sensory ring buffer
  │  2. for each modality, run frozen encoder:
  │     - video → V-JEPA 2 → 1024d
  │     - audio → Wav2Vec-BERT → 1024d
  │     - text  → Llama-3.2-3B → 2048d
  │  3. project each latent to 8192-bit HV via thresholded random projection
  │  4. compute brain-aligned surprise: hamming distance from
  │     predicted-next-signature, threshold calibrated to TRIBE v2
  │  5. if surprise > θ_brain: promote to episodic
  │
  ▼  LAYER 1 — MULTIMODAL BINDING
  │  episode = ROLE_video ⊕ sig_video
  │         XOR ROLE_audio ⊕ sig_audio
  │         XOR ROLE_text  ⊕ sig_text
  │         XOR ROLE_goal  ⊕ sig_goal
  │         XOR ROLE_belief ⊕ sig_belief
  │         XOR ROLE_time  ⊕ sig_time
  │
  ▼  LAYER 3 — STORAGE (same as v2.0)
  │
  ▼
USER gets EpisodeId

The read path — recall()

The four-tier cascade. Recall falls through tiers until it finds matches or hits tier_floor. It never returns the empty set. With agidb v2, retrieval is also goal-biased: active goals up-weight relevant matches.

USER  db.recall("what thai place did sarah mention?")
  │
  ▼  LAYER 2 — PARTIAL EXTRACTION (if natural-language cue)
  │  Extract partial triple shape from the cue
  │
  ▼  LAYER 1 — TIERED RETRIEVAL
  │
  ▼  TIER A — EXACT     canonical entity match via concept index
  │                     confidence 1.0
  │
  ▼  TIER B — SIMILARITY  HDC structured-signature similarity,
  │                       POPCOUNT over inverted-index intersection
  │                       confidence band [0.6, 0.95]
  │
  ▼  TIER C — GIST     raw-text gist signature similarity
  │                    confidence band [0.3, 0.6]
  │
  ▼  TIER D — NEAREST  best-effort nearest neighbours,
  │                    low_confidence flag, confidence ≤ 0.3
  │
  ▼  GOAL-BIAS REWEIGHTING
  │  If active goals exist, up-weight matches semantically
  │  related to those goals (HDC similarity to goal signatures).
  │
  ▼  LAYER 3 — HYDRATION
  │  fetch rows, apply bi-temporal `as_of` filter,
  │  apply supersession filter, attach provenance + beliefs
  │
  ▼  FLOOR 7 — ATTENTION TRACE
  │  emit LearningEvent::AttentionTraced with which signatures
  │  were activated and rejected
  │
  ▼
USER gets Recall { matches, semantic_atoms, beliefs, tier_used, elapsed_ms, attention_trace }

Target: p95 under 50ms on a laptop with 100k episodes. No network calls. No API keys. No LLM in the read path.

The consolidation loop — consolidate()

Runs in the background (default: every 5 minutes when idle) or on demand. The analog of sleep, extended with surprise-gating and learning-log emission.

1. SCAN         scan recent episodic signatures (last 7 days)
2. SURPRISE     compute surprise score for each episode against
                current beliefs and semantic atoms
3. CLUSTER      cluster by hamming distance (similarity ≥ 0.95)
                clusters of N ≥ 3 are consolidation candidates
4. ATOMS        bundle each cluster into a SemanticAtom with
                evidence_count = N and links back to episodes
5. BELIEFS      promote high-confidence semantic atoms to beliefs
                (evidence ≥ 5, no contradictions)
6. CONTRADICT   same (subject, predicate), overlapping valid time,
                different object → older fact superseded
                emit BeliefRevision for affected beliefs
7. DECAY        unreferenced atoms (90 days) decay by factor λ
8. COMPACT      rewrite signatures.dat to drop archived entries
9. AUDIT        emit LearningEvents for every consolidation action
10. SELF-VECTOR (v2)  update self-model EMA: self_vector ← (1-α) self_vector + α bundle(consolidated_atoms)

The unlearn loop — unlearn()

Non-destructive cascading removal. Critical for compliance (GDPR Article 17), security (poisoned memories), and trust.

USER  db.unlearn(UnlearnTarget::Concept("Sarah"), "user requested forget")
  │
  ▼  IDENTIFY CASCADE
  │  Find all episodes, beliefs, semantic atoms, procedures
  │  referencing the target. Compute the dependency graph.
  │
  ▼  TOMBSTONE (non-destructive)
  │  Mark each affected row with t_tombstoned = now.
  │  Signatures invalidated in mmap (compacted later).
  │  Concept HV marked withdrawn.
  │
  ▼  CASCADE
  │  Beliefs whose evidence drops below threshold → confidence
  │  reduced or belief withdrawn. Affected semantic atoms
  │  recomputed without removed evidence.
  │
  ▼  SELF-VECTOR SUBTRACTION (v2)
  │  self_vector ← (self_vector - α · bundle(tombstoned_signatures))
  │  Otherwise the self-model still "remembers" the unlearned
  │  thing as centroid contamination. Real unlearn means
  │  subtracting from the self-model too.
  │
  ▼  AUDIT
  │  Emit LearningEvent::Unlearned with target_ref, cascade_size,
  │  reason, and the full dependency graph that was tombstoned.
  │
  ▼
USER gets UnlearnReport { episodes, beliefs, atoms, procedures, audit_id }

Key design choices

6. The data model

The types stored by layer 3 and exposed through the public API. Defined in crates/agidb-core/src/types.rs and the new modules.

Carried forward from sochdb v1

• HV — a binary hypervector, 8192 bits / 1024 bytes, 64-byte aligned
• Episode — a stored observation with bi-temporal stamps and HDC signature
• Triple — a (subject, predicate, object) tuple with confidence and source-episode back-reference
• Concept — a canonical entity with deterministic HV, canonical name, aliases, type
• SemanticAtom — a consolidated fact bundled from multiple episodes with evidence_count and source-episode provenance
• Procedure — procedural memory: typed shape for a workflow/skill
• Provenance — write attribution: source, session_id, trace_id, metadata
• TimeRange — closed-open valid-time interval [start, end)
• Query / Recall / RecallMatch / SemanticMatch — retrieval request and result types
• Tier — Exact / Similarity / Gist / NearestNeighbor

Added in agidb v2.0

• Goal — id, parent_id, description, state (Active/Paused/Completed/Abandoned), success criteria, deadlines, HDC signature, provenance
• Belief — claim, subject, confidence, evidence (episodes), contradictions, revision_log, bi-temporal stamps, HDC signature
• BeliefRevision — timestamp, previous_confidence, new_confidence, triggering_evidence, reason
• SensoryFrame — raw text or multimodal blob ref, modality, received_at, surprise_score, optional promotion link
• Modality — Text / Image { path } / Audio { path } / Video { path } / Multimodal { components }
• LearningEvent — enum of every introspectable event the system records
• AttentionTrace — per-recall record of which signatures activated and why
• UnlearnTarget — Episode / Belief / Concept / BySource / BySession
• UnlearnReport — cascade summary with audit log reference
• SelfVector — slowly drifting 8192-bit hypervector representing the agent’s current self-model centroid

Added in agidb v2.1

• MultimodalEncoding — { video: Option<HV>, audio: Option<HV>, text: Option<HV> } — modality-tagged signatures
• EncoderConfig — versioned config for V-JEPA 2 / Wav2Vec-BERT / Llama-3.2-3B (model hashes, weights paths, projection matrices)
• BrainCalibration — surprise threshold, fitted parameters, calibration dataset reference, TRIBE v2 version
• BamsScore — six-cortical-network RSA score breakdown

Updated for v2

The Recall struct now includes goal-bias metadata and belief context:

pub struct Recall {
    pub matches: Vec<RecallMatch>,
    pub semantic_atoms: Vec<SemanticMatch>,
    pub beliefs: Vec<BeliefMatch>,           // new in v2
    pub active_goals: Vec<GoalId>,           // new in v2 — which goals biased this
    pub tier_used: Tier,
    pub elapsed_ms: u32,
    pub attention_trace: Option<AttentionTrace>,  // new in v2
}

The on-disk layout (v2.1)

An agidb v2.1 store is a directory containing:

memory.agidb/
├── meta.redb              redb database — 16 tables in v2.1:
│                            Inherited from sochdb v1:
│                              episodes, concepts, concept_by_name,
│                              concept_episodes (multimap),
│                              inverted_index, semantic_atoms,
│                              consolidation_log, manifest
│                            New in agidb v2.0:
│                              goals, beliefs, belief_revisions,
│                              sensory_buffer, learning_events,
│                              tombstones
│                            New in agidb v2.1:
│                              self_vector_history,
│                              encoder_versions
├── signatures.dat         mmap'd flat file — 1024-byte HV slots
├── manifest.toml          format version, hyperparams, schema version,
│                          encoder config hashes
├── audit.log              append-only signed audit log (optional, v0.3+)
└── encoders/              v2.1: ONNX weights, projection matrices
    ├── vjepa2-gigantic-256.onnx
    ├── wav2vec-bert-2.0.onnx
    ├── llama-3.2-3b.onnx
    └── projections.bin    seeded random projection matrices

Bi-temporal columns live on every fact. The on-disk format is versioned via format_version in the manifest; migrations are explicit, never silent. agidb v2 can read sochdb v1 files directly (the v1 schema is a subset of v2). agidb v2.1 can read v2.0 files (v2.0 stores have no multimodal signatures, those tables are simply empty).

7. The build roadmap

The 12-month plan: agidb v2.0 substrate at month 9, agidb v2.1 brain-alignment + BAMS at month 12. Decision gate at week 12 binding.

Guiding principles

• Inherit, don’t rewrite. Every line of sochdb v1’s working code carries forward.
• Ship small. v2.0 is the smallest credible AGI substrate. v2.1 adds brain-alignment on top.
• Benchmark honestly. Every claim is reproducible; publish raw logs. Include cognitive benchmarks. Include BAMS.
• Defer hosting. Stay embedded; cloud is v0.5+ territory.
• Decision gate at week 12. If the numbers don’t justify the bet, reposition.

Phases inherited from sochdb v1 (carry forward)

Phases 0, 1, 2, 4, 6 already complete. Phases 3, 5 remain on the critical path.

Phase 3 — Extraction (sochdb v1 carryover) ⬜

Vendor / port the GLiNER ONNX loading + inference code from ctxgraph. The Extraction pipeline: entities, relations, time anchors, confidence propagation, alias resolution, predicate canonicalization. New for v2: belief extraction.

Exit criterion: observe() extracts triples from 20 sample observations with >85% F1 against a human-labelled gold set. Belief extraction extracts >70% of explicit beliefs correctly. Unlocks tier B and alias resolution.

Phase 5 — MCP + Python bindings (sochdb v1 carryover) ⬜

agidb-mcp MCP server, agidb-py pyo3 bindings with async support, Python wheels.

Exit criterion: Claude Desktop uses agidb as a memory tool via MCP; pip install agidb works.

Phase 7 — Decision gate ⬜

Run benchmarks against Mem0, Zep/Graphiti, Letta, MemMachine on LongMemEval-S + LoCoMo + BEAM using a shared harness, publishing the full six-metric stack plus cognitive benchmark results.

New phases for the AGI pivot (v2.0)

Phase 9 — Cognitive primitives ⬜

Implement Goal and Belief as first-class types. New redb tables. Belief revision math. Goal state machine validation.

Exit criterion: can set_goal, revise_goal, assert_belief, revise_belief, what_do_i_believe, retrieve goals and beliefs through unified recall. 100-step goal mutation test passes. Belief revision audit log captures every change.

Timeline: weeks 13-18.

Phase 10 — Sensory + self-model ⬜

Implement SensoryFrame ring buffer with surprise gating. Extend consolidation_log into learning_events log. Add attention_trace to recall path. Implement what_did_i_learn introspection API. Add self_vector EMA in the self-model floor.

Exit criterion: sensory buffer ingests 1000 frames/sec; surprise gating promotes only ~5% to episodic. Learning log captures every state change. Attention traces survive recall round-trips. Self-vector drifts with consolidation, subtracts on unlearn.

Timeline: weeks 19-22.

Phase 11 — Unlearn API ⬜

Implement unlearn(target, reason) with cascading removal. Tombstone model. Cascade through dependent beliefs, semantic atoms, procedures. Self-vector subtraction. Audit log retention permanent.

Exit criterion: unlearning a concept removes all references within 100ms. Audit log permanent. Self-vector verifiably no longer contains the unlearned concept.

Timeline: weeks 23-25.

Phase 12 — Neurosymbolic interface ⬜

Expose the implicit signature ↔ triple translation as a first-class API. Implement neurosymbolic_query with weighted hybrid. Add signature_to_triples and triples_to_signature.

Exit criterion: hybrid queries with 50/50 weights return appropriately blended results.

Timeline: weeks 26-27.

Phase 13 — Cognitive benchmarks ⬜

Build cognitive-bench suite. Goal consistency, belief revision, unlearn cascade, multi-floor retrieval tests.

Exit criterion: all four cognitive benchmarks pass with documented thresholds.

Timeline: weeks 28-30.

Phase 8 — Hardening + launch (v2.0 substrate ships) ⬜

Expand the harness, fuzz suite, 30-day soak test, arxiv whitepaper, 3 design-partner deployments, launch blog post, demo video, crates.io + PyPI + MCP-registry publication.

Public v2.0 launch at week 36 (month 9).

New phases for v2.1 brain-alignment

Phase 14 — Multimodal sensory encoders ⬜

New crate agidb-sensory. Wrap V-JEPA 2 (Gigantic-256), Wav2Vec-BERT 2.0, Llama-3.2-3B via ONNX or Candle. Implement Charikar 2002 thresholded random projection from each encoder’s latent dim to 8192-bit HV. Extend observe_multimodal() API.

Exit criterion: end-to-end pipeline: 30s video+audio clip → V-JEPA 2 + Wav2Vec-BERT inference → projected to 8192-bit episode HV → stored in redb. P50 latency ≤ 2s per 30s clip on a laptop.

Timeline: weeks 37-42 (6 weeks).

Phase 15 — Brain-calibrated surprise gating ⬜

Build calibration tooling. Download TRIBE v2 weights from HuggingFace. Run TRIBE v2 on paired stimulus dataset. Compute neural surprise as deviation of associative-cortex BOLD from sliding-window baseline. Fit agidb surprise threshold θ_brain to maximize correlation with TRIBE-predicted neural surprise indicator.

Exit criterion: calibrated threshold ships in v2.1. Documentation includes reproducible calibration recipe. Comparison plot: pre/post calibration vs neural surprise.

Timeline: weeks 43-46 (4 weeks).

Phase 16 — BAMS benchmark + paper ⬜

Build agidb-bams crate. Six-cortical-network RSA harness. Compute TRIBE-predicted RDMs over held-out movies. Compute agidb signature RDMs. RSA. Run baselines: raw V-JEPA 2 latents, mem0, letta, zep/graphiti, hippoRAG.

Exit criterion: BAMS score reported for all baselines and agidb. Paper submitted to ICLR 2026 MemAgents workshop or CCN 2026 (whichever has the earlier deadline). Public repo with reproduction kit.

Timeline: weeks 47-52 (6 weeks).

Beyond v2.1

See AGI_TRAJECTORY.md for the 5-year roadmap.

Explicitly out of scope (any version)

Distributed/sharded agidb, a query language, a UI, replacing vector DBs for document RAG, replacing graphs for general graph workloads, a fine-tuning service, building AGI itself.

8. Brain-alignment in v2.1+

Why it’s separate from v2.0: the substrate has to land first. Brain-alignment is additive, requires GPU-class compute for encoder inference, and depends on cognitive primitives that ship in v2.0 phases 9-13.

The integration in one paragraph: v2.1 ships agidb-sensory, a Rust crate that wraps Meta’s V-JEPA 2 (video, 1.2B params), Wav2Vec-BERT (audio), and Llama-3.2-3B (text). Each encoder outputs a dense latent that gets projected to an 8192-bit signature via Charikar 2002 thresholded random projection (training-free, JL distance preservation guarantee). Multimodal episodes are bound via VSA role-filler binding so individual modality signatures remain factorable. Sensory surprise is computed against the predicted-next-signature, with threshold empirically calibrated against TRIBE v2’s predicted fMRI BOLD across 720 subjects.

Why this is defensible: because agidb uses the same encoder stack as TRIBE v2, its internal representations can be compared directly against human cortical activations on matched stimuli. This is the brain-alignment benchmark (BAMS) and the first paper-sized contribution from the project.

See BRAIN_ALIGNMENT.md for the full technical detail. See BAMS_BENCHMARK.md for the benchmark protocol and paper plan.

9. Feature catalogue

Storage & durability (inherited from sochdb v1)

Retrieval (mostly inherited, extended in v2)

Extraction — layer 2

Consolidation (mostly inherited)

Cognitive primitives — new in agidb v2

Brain-alignment — new in agidb v2.1

Interfaces & distribution

10. Tech stack

Rust top to bottom in agidb-core (constitution article VIII). ONNX runtime via the ort crate is the only permitted FFI for v2.0. v2.1 adds Candle as an additional ML inference backend option.

Workspace — 11 crates (v2.1 expanded from v2.0’s 9)

Key dependencies

MSRV: Rust 1.89. License: Apache-2.0.

Performance targets (v2.0, on an M2 / i7-12700H benchmark laptop)

Additional performance targets (v2.1)

11. The decision gate

Phase 7, week 12. Same binding gate as sochdb v1. The entire 9-month bet collapses to one week of benchmarks. The project commits, repositions, or retreats.

The benchmark suite

Every run publishes all six metrics plus the cognitive benchmark results — never a single number: BLEU + F1 + LLM-judge + token cost + p95 latency + noisy-cue degradation + cognitive primitive correctness. Raw logs + the harness commit hash ship with every claim.

The thresholds

Commit (proceed to launch + v2.1 + fundraise) — all of:

• agidb ≥ Zep/Graphiti accuracy on LongMemEval-S (within 1pp F1 and LLM-judge)
• ≥ 3× lower p95 retrieval latency than Mem0
• ≥ 3× lower token cost than Mem0 (target < 2,500 tokens/query)
• wins the noisy-cue degradation test
• passes all four cognitive benchmarks (goal, belief, unlearn, multi-floor)
• holds across all three standard benchmarks (no cherry-picking)

Reposition (ship smaller, no fundraise) — within 3pp of Mem0 F1 and ≥ 10× memory savings, even if cognitive benchmarks are partial. Reposition as “agidb-lite: embedded cognitive memory for edge agents.” Skip v2.1.

Retreat (fold back into ctxgraph) — more than 10pp behind dense baselines and the gap doesn’t close with reranking. Reposition as “ctxgraph: temporal graph memory for agents.”

What success looks like at 9 months (v2.0)

• Match/beat Zep/Graphiti on LongMemEval-S (≥ 64 accuracy)
• ≥ 3× lower retrieval latency than Mem0 (p95 < 50ms)
• ≥ 3× lower token cost than Mem0 (< 2,500 tokens/query)
• All four cognitive benchmarks pass
• 1M+ episodes on a laptop with sub-100ms p99 recall
• cargo add agidb + pip install agidb both work
• An MCP server any MCP-compatible agent can use
• 1000+ GitHub stars, 5+ design-partner deployments
• arxiv whitepaper posted

What success looks like at 12 months (v2.1)

• v2.0 success criteria all hold
• Multimodal observe_multimodal() API ships
• Brain-calibrated surprise threshold released with reproducible calibration recipe
• BAMS benchmark harness published with baselines (mem0, letta, zep, hippoRAG, raw V-JEPA latents)
• ICLR 2026 MemAgents workshop paper accepted (or CCN 2026, whichever lands first)
• agidb wins BAMS in associative-cortex networks (DMN, dorsal attention, frontoparietal)
• 5000+ GitHub stars
• 10+ design-partner deployments
• Seed round closed

If these are met, agidb is a category-leading substrate. If not, the brain-alignment work folds back into a v2.2 retry or gets abandoned in favor of pure-substrate evolution.

12. The 5-year trajectory

The full roadmap from agidb v2.0 (substrate, 2026) to v2.5 (AGI-grade, 2031). Detailed in AGI_TRAJECTORY.md. Summary:

This is a 5-year commitment. The 12-month v2.1 launch is the first major milestone, not the whole project.

13. How to navigate the project

Docs

The constitution in one breath

18 immutable principles (14 inherited from sochdb v1, 3 new for v2.0, 1 new for v2.1). See CONSTITUTION.md. Anything that contradicts the constitution needs an ADR.

Build & test

cargo build --workspace                          # all 11 crates
cargo test  -p agidb-core                        # 44+ tests
cargo clippy --workspace --all-targets -- -D warnings
cargo bench -p agidb-core --bench hdc_scan       # the 100k hamming scan
cargo bench -p agidb-bench --bench cognitive     # v2.0 cognitive benchmarks
cargo bench -p agidb-bams  --bench bams_full     # v2.1 BAMS suite

The immediate next steps

1. Rename + push to GitHub — create the agidb/agidb org/repo. transfer the sochdb v1 commits. configure the remote. push the rebranded codebase.
2. Buy agidb.ai + agidb.dev + agidb.io + agidb.co — lock the namespace today.
3. Reserve agidb on crates.io, npm, PyPI — lock the package names.
4. Phase 3 — extraction — vendor GLiNER ONNX from ctxgraph; unlocks raw-text observe, tier B, and alias resolution.
5. Phase 5 — MCP + Python — make the engine consumable from Claude Desktop and pip install.
6. Phase 9 — cognitive primitives — implement Goal and Belief as first-class types. This is the v2.0 wedge.
7. Phase 7 — the benchmark harness — build agidb-bench, run the decision gate at week 12.
8. Phase 14-16 — v2.1 brain-alignment — only after v2.0 decision gate passes. ship V-JEPA 2 sensory + BAMS + paper by month 12.

agidb v2 is pre-alpha. The one-liner: the cognitive substrate for autonomous AI agents — content-addressable hyperdimensional memory, first-class goals and beliefs, bi-temporal supersession, sleep-like consolidation, and a non-destructive unlearn primitive. One Rust binary, one API, no query language. The database AGI systems will run on top of. v2.1 extends with brain-aligned multimodal sensory and the BAMS benchmark.