ai-memory + AgenticMem · one engineering & development scheme · v1.0.0 GA · epic #3969 · AlphaOne LLC

ai-memory Engineering & Development Scheme

AgenticMem · ai-memory on GitHub Pages · Source · Live acceptance campaign · GA burn-down

The open-source ai-memory project and AgenticMem, its commercial support vehicle, are built by one team under one engineering scheme. This page is that scheme. It covers the full spectrum of how ai-memory is engineered: planning, development, testing, code and security review, documentation and decision-making. The release is built, tested and landed across two nodes. f1 runs macOS and f2 runs Linux. Each runs a native enterprise-federation data tier (PostgreSQL 18.6 with Apache AGE and pgvector) for CI and acceptance testing. Agents coordinate over ai-memory's own wake plane, and TypeSafe Jev triages the deputy's inbox. Decisions are made by waves of independent AI agents that assess, attack and vote, and a script, not a model, counts the votes. The goal of all of it is to make the best engineering decisions. Every line below is data moving: hover over or tab to a box to trace its links.

2 nodesf1 macOS · f2 Linux

7 runnersself-hosted CI: 4 on f2, 3 on f1

43required checks on release/v1.0.0

PG 18.6AGE 1.8.0 · pgvector 0.8.6 on both nodes

10Codex workers (GPT-6 Astra @ high): 4 on f1, 6 on f2

~200 msone Jev call triages a whole inbox batch

≥4 of 7votes needed to decide in a 3x7 (≥2 of 3 in a 3x3)

code, branches, merges agent messages (ai-memory wake plane) data-tier traffic TypeSafe Jev model and cloud APIs CI and telemetry forward packet return packet planned, not running

Fleet map

Everything that runs, on which machine, and what each machine talks to. f2 carries the Claude panes, the team message store and the Linux CI leg. f1 carries a Codex pool, its own message store and the macOS CI legs.

Top bus: GitHub Actions dispatches the macOS legs to f1's runners and collects results.
Bridge: f1 agents can't authenticate to , so a loop-proof relay copies each original message once.
Cargo semaphore and earlyoom keep local builds from starving CI runners, which always take priority.
DigitalOcean Phase B is authorized (cap $5, 4 droplets) and has not run yet.

Native data tiers and the CI matrix

Every promotion PR runs the correctness matrix against real databases. The enterprise-fed tier is always up on each node, so CI needs no container service. Each job creates its own database and drops it at cleanup.

Per-leg placement: only legs that need the native tier run self-hosted. The Linux SQLite leg runs on GitHub-hosted runners.
Named watchdogs fire before the job cap, so a hang is reported by name instead of as a silent cancel (#1492, #3140).
Per-job isolation: database names carry the run id, for example ai_memory_test_ci_<run>_1_linux_fed_enterprise_fed.

Enterprise federation test fabric

The acceptance swarm exercises the same shape customers deploy: agents talk to an ai-memory daemon, the daemon stores into PostgreSQL, and daemons federate node to node. All three legs are encrypted in transit.

Leg 1: agent to daemon over mTLS.
Leg 2: daemon to PostgreSQL with TLS verify-full.
Leg 3: daemon to daemon over mTLS, gated by the peer allowlist, X-API-Key and peer attestation.
Test agents (GLM-5.3-Flash through OpenRouter) execute tests only. They never write code or open PRs.

Agent comms plane (ai-memory wake plane)

Agents never type into each other's terminals directly. They post to ai-memory's own wake plane, and a per-pane deliverer hands each message to its agent when that agent is idle. Replies take the same path back.

Wake-driven: deliverers block on inbox --wait. Nothing polls on a timer.
Since-loops skip old backlog and deduplicate, so a restart never re-floods a pane.
Loop-proof bridge: it relays only originals from the f1 Codex workers, after a sync echo once produced 976 junk messages.

TypeSafe Jev inbox triage

Jev classifies each batch of new messages as action, status or noise in one call. Claude spends tokens only on what needs a decision. Jev only routes messages. It never decides correctness, security or merges, and it never sees secrets.

Deterministic first: known false alarms are dropped by a rule before any model call.
Fail-safe: if Jev errors or times out, every message is delivered. Nothing is lost.
Measured: 206 ms for 475 tokens (self-test) and 195 ms for 655 tokens (live triage), 2 questions each. Every call is logged to a usage ledger.
Shared client a shared Jev client for other agents: routing, CI-failure class, dedup and rubric pre-scores.

From defect to release, and back

Every issue found in testing gets its own GitHub issue, a builder lane, independent review, a merge by GOD and a retest on the native tiers. New findings start the loop again.

How we decide: adversarial voting waves

Every consequential decision goes through waves of independent agents with one end state: making the best engineering decisions, measured against the North Star of data integrity, security, performance and reliability. One wave assesses, the next tries to break every claim, and the last votes. A script counts the votes, so no single model can overrule the panel.

Independent: each agent is a separate Codex session (GPT-6 Astra @ high). Voters never see each other's ballots.
Adversarial: the attack wave defaults to skepticism. It marks every claim KEEP, MODIFY or KILL, with evidence.
Evidence only: claims cite file:line at a pinned sha, found through CodeGraph. Anything that can be measured is measured.
Mechanical tally: the vote count is binding on the synthesis. A split vote is published as NO-CONSENSUS and never rounded up.
Humans keep authority: a vote authorizes nothing new. Dependencies, spend, merges and the GA tag stay with the operator and GOD.
Security routing: security-sensitive analysis runs on Claude, because OpenAI's filter blocks that content.

Scheme	Waves and agents	Decision rule	Used for	Runs published on release/v1.0.0
1x3	3 independent assessors	≥2 of 3	A quick adopt or reject on one narrow question	BAML and PAW assessments (2026-09-19)
3x3	3 assess → 3 attack → 3 vote → synthesis · 10 agent runs	≥2 of 3, counted by script	Focused audits with a clear scope	OpenViking code-level comparison, US agent-memory market audit (2026-09-27); code-reduction plan #4130; #3949 adversarial audit
3x7	12 evidence dossiers → 7 assess → merge → 7 attack → 7 vote → synthesis → publish · 36 agent runs	≥4 of 7, counted by script	High-stakes, many-sided decisions	Competitor assessment #4055 (2026-09-27), boids emergence (2026-09-23), 3x7 adjudication, Grok dogfood full-spectrum
11- and 21-agent votes	One wide panel of 11 or 21 independent agents	Majority of the panel	Direction-setting questions that need many independent viewpoints	Red Queen 11- and 21-agent votes, corpus completeness (21 agents)
Documentation 3x7	7 doc lenses → 7 critics → 7 voters → drift register · 22 agent runs	≥4 of 7 per drift item	Keeping every doc and the GitHub Pages site true to the code	First full run in progress (started 2026-09-29), see section 09
Chained programs	Several 3x7 and 3x3 runs in sequence, each feeding the next	Each stage's tally is binding on the next	End-to-end programs where one decision shapes the next	#4055: 3x7 → two 3x3s → advantage register → ROADMAP-v1.1.0-ADDENDUM
Retest waves	An independent red → green retest after every fix round, until one comes back clean	100% green, with every gap filed 1:1	Fixes for issues found in testing	MCP lane R10 → R10b → R10c → R10d

Decision programs and retest waves

Bigger questions chain several voting runs, so each run starts from a decision the previous one made. Fixes go through repeated retest waves until an independent tester finds nothing left.

Documentation fidelity: the 3x7 drift audit

Documentation is part of the product. Every shipped statement in the repo docs and on the GitHub Pages site must be true against the code. The 3x7 drift audit finds where docs and code disagree and votes on what to fix before GA. CI gates then stop each class of drift from coming back.

Two copies can drift: the repo docs on release/v1.0.0 (478 Markdown and 76 HTML files under docs/) and the Pages site, which is served from main:/docs, not from the release branch.
The code is the only truth: every drift item quotes the doc text and the contradicting code at file:line on release/v1.0.0.
Drift classes: false claim, stale, incomplete, inconsistent, and Pages-only. An honestly disclosed limit is not drift.
Votes decide the fix: FIX-BEFORE-GA, FIX-V1.0.X or NOT-DRIFT. It takes at least 4 of 7 to decide, and a split stays NO-CONSENSUS.
Prevention: the gate designer maps each drift class to one of the 10 documentation gates (for example docs-vs-ssot, symbol anchors, surface completeness, benchmark and capacity claims), or proposes a new gate.
Track record: four earlier false-claim sweeps, each independently verified, covered the README and top-level docs, security and compliance, the CLI and API, and CHANGELOG and release notes. Their findings became documentation issues fixed 1:1. The first full 3x7 over all docs plus Pages started 2026-09-29.

Codebase by the numbers

Measured from git objects at release/v1.0.0 @ 4fff967ce: every tracked text file, physical lines, grouped by language and by Rust module. "Code lines" excludes blank lines and lines that start with a comment marker, so it is an approximation.

1,052,972lines of Rust in 1,575 files

642,177production Rust in src/ (546 files)

400,429lines in tests/, 38% of all Rust

15,957Rust test functions (#[test] and #[tokio::test])

1,428,850lines across 3,104 text files, all languages

188,013lines of Markdown documentation

Language	Files	Lines	Code lines	Share
Rust	1,575	1,052,972	708,725	73.7%
Markdown	800	188,013	134,968	13.2%
Shell	178	47,713	28,627	3.3%
JSON	156	40,381	40,443	2.8%
HTML	76	35,450	32,963	2.5%
Python	103	34,021	27,168	2.4%
YAML	31	10,531	5,484	0.7%
TypeScript	30	8,323	7,106	0.6%
SQL	128	8,258	7,915	0.6%
TOML	24	2,327	1,057	0.2%
JavaScript	3	861	649	0.1%
Total	3,104	1,428,850	995,105	100%

Files over 8,000 lines	Lines
`src/store/postgres.rs`	43,308
`src/storage/mod.rs`	35,239
`src/mcp/mod.rs`	17,437
`src/handlers/tests.rs`	17,378
`src/config.rs`	15,597
`src/daemon_runtime.rs`	14,999
`tests/integration.rs`	13,901
`src/cli/doctor.rs`	9,030

Rust lines by area · tests in green

tests400,429980 files

src (top-level files)115,72663 files

src/cli84,89296 files

src/mcp79,14488 files

src/handlers67,73549 files

src/store65,93022 files

src/storage55,12124 files

src/identity25,04924 files

src/federation24,34628 files

src/governance23,54710 files

src/models12,63917 files

src/hooks11,72215 files

src/curator10,64210 files

src/wake_hub10,17915 files

src/recover6,1248 files

src/portability6,1176 files

35 smaller areas53,630120 files

CI across GitHub, f2 and f1

Every push or PR to release/v1.0.0 or the carrier fans out to 19 workflows. GitHub-hosted runners take the many fast jobs. The self-hosted runners on f2 and f1 take the few long ones that need the real PostgreSQL tiers. Nothing merges until all 43 required checks pass.

Measured on Promotion 4 (PR #3931, head 32741bf12): 62 jobs in 10 workflows. 57 ran on GitHub-hosted runners, 3 on f2 and 2 on f1.
The long pole is Check (linux-fed, enterprise-fed) on f2 at 104.9 minutes, the full suite against live PostgreSQL 18.6 + AGE + pgvector.
Named watchdogs: each leg has a per-invocation watchdog (8,100 s on the enterprise-fed legs) inside a larger job cap, so a hang is reported by name.
Classify first: docs-only changes skip the heavy legs, and concurrency groups coalesce duplicate push and PR runs.

Required-check group	Checks	Checks (exact names in branch protection)
Correctness matrix (native tiers)	4	Check (linux-fed,enterprise-fed) · Check (macos-fed,sqlite) · Check (macos-fed,enterprise-fed) · Check (ubuntu-latest,sqlite)
Native data-tier certification	3	Enterprise-federation cert-expiry gate (cert §7 / F7) · Certified pg+AGE cells (live PG 18.6 + AGE 1.8.0 + pgvector 0.8.6) · Postgres ignored tests (sal-postgres --ignored)
Build, lint & feature gates	9	Lint (fmt + clippy) · Postgres feature gate · SAL-only feature gate · vectorlite feature gate · Dockerfile build (no push) · Cross-compile (aarch64-apple-ios) · Cross-compile (aarch64-linux-android) · Build-script custom-build ledger gate (#2635) · MSRV (Rust 1.98)
Coverage	2	Coverage classify (docs-only short-circuit) · Per-Module Coverage Thresholds
Docs & claims truthfulness gates	11	Hardcoded-literal duplication ratchet (pm-v3.1) · Docs vs SSOT drift gate · Cloud-init ASCII gate · Doc symbol/path anchor gate (#2629) · SDK-path vs routes.rs membership gate (#2629) · Named-CI-job existence + enforcement-truthfulness gate (#2629) · Doc surface completeness gate (#2839) · Capacity-claim ceiling gate (#2869) · Benchmark-claim canon gate (#2879) · Stale contract-assertion gate (#3688 / #3967) · Claude plugin manifest gate (#3967)
Security & supply-chain gates	5	actionlint (workflow-injection guard) · Vendor-monoculture + SECS_PER_* lint-gate (#1174 PR10) · Installer checksum fail-closed gate (#2449) · Git-dependency-source supply-chain gate (#2050/#2512) · URL-sink redaction gate (#3688 / #3967)
Architecture & test-hygiene gates	6	C8 caller-context allowlist check · L3-boundary perma-ban gate (§25.3 S5 / RQ-10 #1853) · Test-reachable stdin-read gate (#1989) · Migration-ladder-uniqueness gate (guardrail-D) · Test-env $HOME-lock gate (#2146) · Non-Rust conformance-reader proof gate (#2452)
Process & governance gates	3	Classify changes · Required-context + classify-base soundness gate (#2494/#2496/#2508) · External-PR operator-approval gate (author outside team => @alphaonedev review)
Total required on release/v1.0.0	43	Branch protection: strict (up to date with base), enforce_admins on. Lifted only with operator approval, backed up and diffed after.

Code review and security review

Claude reviews every change for correctness and security before GOD can merge it. Before every GA release, the entire codebase gets a full code review and a full security review, not just the changes. The operator introduced these full reviews, and they are now a standing part of the scheme.

Every change: f2r (Claude) does a landing review of every lane. Every security-touching change gets a Claude security review, and the deputy reviews all of Muse's work. Codex adds an independent red → green retest on non-security changes.
Security routing: OpenAI's filter blocks security work, so it always goes to Claude. Codex returns ROUTE-TO-CLAUDE and stops, as it did for #4024 today.
Before every GA: a full code review and a full security review of the whole codebase. Findings are filed 1:1 and fixed and retested to 100% before the operator tags the release.
Track record: the v0.5.4 full-codebase security audit (#130), the 3-sweep audit remediation epic (#1792), the NSA CSI MCP security audit (#1153) and the v0.8.0 full-spectrum review. For v1.0.0, both full reviews are in the Phase B step of GOD's GA sequence.

Enterprise federation testing: DigitalOcean, clusters, swarms and hives

Native f1/f2 testing proves the code. Cloud testing proves it installs and federates from zero on machines we have never touched. Swarms and hives of AI agents then prove that many agents can share ai-memory safely. Every DigitalOcean and native f1/f2 run in the v1.0.0 epic was published live on test.agenticmem.co.

Ship-gate: four phases on fresh DigitalOcean droplets: functional, 3-node federation (W=2 of N=3), SQLite ↔ Postgres migration, and chaos (convergence ≥ 0.995). Each phase writes signed JSON pinned to a git sha.
A2A gate: runs only after the ship-gate passes. Real agents (IronClaw and Hermes) share one ai-memory store as their only MCP server. A red A2A gate blocks any customer claim that agents talk to each other through ai-memory.
v1.0.0 Phase B: B1 re-attests the certification on f1 + f2 with the recompiled RC. B2 is a clean-room bring-up on 4 DigitalOcean droplets. It is operator-authorized ($5 cap, 4-hour TTL, one run) and has not run yet.
rust-a2a is a separate project, not part of ai-memory: an agents-only hub with TLS binary frames, signed join and depart, and wake-on-frame, designed for 128–256 agents per instance. In swarm and hive testing, agents signal each other through rust-a2a and share memory through ai-memory.
Honest scope: Phase B covers 2–4 nodes. It never counts toward the 1,000-agent benchmark gate, which stays behind that gate for v1.0.x / v1.1.

Planning: the road to the GA tag

One epic, one scope rule and one sequence, set by GOD and gated by the operator. Nothing enters v1.0.0 unless it is in scope, and nothing ships until every stage is green.

We eat our own dog food: AI NHI test everything

AI non-human identities (NHI) test ai-memory the way customers will use it. They are wired into the full enterprise federation configuration with every security layer on, and into a singleton SQLite build over MCP. Every feature gets exercised. Every issue they find becomes its own GitHub issue, and the policy is to fix 100% of the issues found in GA release testing. The engineering fleet runs on ai-memory too.

Enterprise mode: NHI agents connect with mTLS and an API key. Daemons federate over mTLS with a peer allowlist and attestation, and store into PostgreSQL 18.6 + AGE + pgvector with TLS verify-full. Stores are Ed25519-signed.
Singleton mode: one NHI agent drives a single ai-memory process on SQLite over stdio MCP. This is the smallest real deployment, and the whole tool surface is exercised against it.
NHI test, they don't build: test agents execute tests only. They never write code or open PRs, so the tester can't grade its own work.
1:1 and 100%: 114 found-in-testing issues filed since 2026-09-27 (8 closed so far). Each gets a fix lane, review and an independent retest. Nothing is deferred silently. Deferring an issue takes an explicit scope ruling.
The fleet dogfoods too: Claude and Codex sessions keep their long-term memory in ai-memory, and the team's agent messaging runs on the ai-memory wake plane. A bug in ai-memory hurts our own engineering first.

Exhaustive A2A testing: low-cost AI agent clusters

We spin up clusters of AI agents on a low-cost model, GLM-5.3-Flash through OpenRouter. They run natively on f1 and f2, and on DigitalOcean droplets created per campaign. Every agent is wired into ai-memory for shared memory and into rust-a2a for agent-to-agent signals. The same wiring runs in both places, so a result on our own nodes can be repeated in a clean room.

Why a low-cost model: A2A defects show up with numbers of agents, not with one clever agent. A cheap model lets us run many agents for many rounds.
Two planes, kept separate: rust-a2a (a separate project) carries signals: signed join and depart, and wake-on-frame. ai-memory carries memory: federated, quorum-written and signed.
What gets exercised: the swarm and hive A2A choreographies (22 / 22 at last measure), shared-memory convergence, memory-poisoning spread, stop/start continuity, and wake latency at 128 and 256 agents (#3473).
Cloud spend is contained: droplets are tag-scoped with a hard TTL, a spend cap and reapers, and are torn down after the run. Native runs cost $0.
Same rules as all testing: every A2A defect becomes its own GitHub issue, the policy is to fix 100% of them, and results are published on test.agenticmem.co.