The Context Governor for agent loops.
Artesian governs what one agent loop holds in force: what enters the context (a qualify-gate), what it costs (a token budget), what survives compaction and disconnects (anchors + committed state), and why — every admit/reject decision in an append-only audit log. The mechanism is a memory control plane; the role it plays in your loop is the governor. Memory stays small, high-signal, and survivable — the agent acts on what it knows, not re-reads everything it has ever stored.
- Bounded committed context (ACC) — a qualify-gate (drift / novelty / relevance) decides what enters; the controller evicts under saturation and compresses to fit; never silently loses critical state.
- Survives compaction — deterministic session anchor + targeted recall; resumes correctly after any context reset, auto-compaction, or disconnect.
- Token-efficient retrieval — ~1,000 tokens per query regardless of memory size (99.9% saving vs full-context replay at 1M tokens; see Proof).
- Private, zero-cost writes — no per-write LLM call; local by default; LLM judge, consolidation, and compression are opt-in.
- Composable — ACC over any vector store; Qdrant / pgvector / sqlite-vec / files / mem0; bring your own judge and compressor; any MCP agent.
recall candidates (from durable memory)
│
▼ qualify-gate: drift / novelty / relevance
┌───────────────────────────────────────┐
│ Committed Context State (bounded) │ ← what the agent sees
│ ┌───────────────────────────────┐ │
│ │ decision: chose Rust+tokio │ │
│ │ plan: shard the embedder │ │
│ │ blocker: GPU quota at limit │ │
│ └───────────────────────────────┘ │
└───────────────────────────────────────┘
│ evict / compress under saturation
▼
durable memory (sqlite-vec / Qdrant / pgvector / files)
↑ anchor + targeted recall on any compaction
# Install — pre-built binary, no Rust toolchain (macOS + Linux):
brew install aquifer-labs/tap/artesian
# (or build from source: cargo install --git https://github.com/aquifer-labs/artesian artesian-cli)
artesian init --backend sqlite-vec # zero infrastructure
artesian memory store "chose Rust+tokio" --tag decision
artesian memory find "which language"
artesian tokens # how many tokens recall has saved so farMCP drop-in (Claude Code, Codex, opencode — any MCP client):
artesian init writes the config. artesian perf prints live proof that memory is working.
Artesian's per-query cost stays flat at ~1,000 tokens while full-context replay grows 81×.
| Memory / history | Full-context replay | Artesian | Saving | Retrieved |
|---|---|---|---|---|
| ~13k tokens (180 docs) | 12,902 | 876 tokens | 93% | 100% |
| ~119k tokens (1,600 docs) | 118,566 | 974 tokens | 99.2% | 100% |
| ~478k tokens (6,400 docs) | 477,740 | 992 tokens | 99.8% | 100% |
| ~1M tokens (14,000 docs) | 1,046,431 | 1,046 tokens | 99.9% | 100% |
just bench-check # reproduce all tiers; fails if committed results differ
→ Full methodology, charts, large-source retrieval: benchmarks/README.md
| Benchmark | Score | Method |
|---|---|---|
| LoCoMo | 0.475 | vector + BGE reranking (vector-only baseline: 0.37) |
| LongMemEval (oracle) | 0.70 | vector retrieval |
The gauge agentic eval harness ships in this repo: multi-session tasks where success = correct next action given accumulated memory, not just recall of a fact (MemoryArena framing, arXiv:2602.16313). Published scores vary by model and task set — run just bench-agentic to measure on your own setup.
→ Methodology: benchmarks/comparison/README.md
Artesian is built like LEGO — take only the pieces you need, bring your own for the rest.
| Store / layer | Role | How to use |
|---|---|---|
| sqlite-vec | Local vector store — zero infrastructure | backend = "sqlite-vec" (default init) |
| Qdrant | Shared vector store — multi-agent / multi-operator | backend = "qdrant" + QDRANT_URL |
| pgvector | PostgreSQL-native vectors | features = ["pgvector"] |
| plain files | Human-readable headwater files (formerly called OKF inside this project; not to be confused with Google's Open Knowledge Format, an adjacent organizational-knowledge layer our OCF spec composes with) — no DB needed | backend = "files" |
| mem0 | Existing mem0 store | Implement headgate::RecallStore |
| headroom | Data-plane compression — shrinks artifact bytes | headroom feature + HeadroomCompressor |
| Ollama / LM Studio / mlx | Local LLM for judge or compressor | provider: "ollama" / "lm-studio" / "mlx" |
| Any OpenAI-compatible endpoint | Cloud or self-hosted LLM | provider: "openai-compatible" + base_url |
| Any agent CLI | Codex / Claude Code / Gemini / opencode | provider: "command" — shelled out via stdin/stdout |
Qualitative only — architectures differ enough that cross-system benchmark numbers mislead.
| Artesian | mem0 | LangMem | plain markdown | |
|---|---|---|---|---|
| What it is | ACC control plane + memory | Managed memory API | LangGraph memory layer | Files + prompting |
| Self-hosted, zero infra | ✓ sqlite-vec or files | Cloud-first | Requires LangGraph runtime | ✓ |
| No per-write LLM call | ✓ | ✗ | ✗ | ✓ |
| ACC qualify-gate | ✓ drift/novelty/relevance | ✗ | ✗ | ✗ |
| Compaction survival | ✓ anchor + recall | ✗ | ✗ | ✗ |
| Multi-writer, isolated | ✓ optimistic CAS | partial | partial | ✗ |
| Agentic eval harness | ✓ ships in repo | ✗ | ✗ | ✗ |
📖 Full documentation site: https://aquifer-labs.github.io/artesian/ (rendered from docs/).
| Architecture | docs/architecture.md |
| Memory internals | docs/memory.md |
| Backends + quantization | docs/backends.md |
| Self-repair after compaction | docs/self-repair.md |
| Concurrency + multi-writer | docs/concurrency.md |
| Composability | docs/composability.md |
| Why Rust | docs/why-rust.md |
| Positioning / prior art | docs/positioning.md |
| Onboarding | docs/onboarding.md |
| MCP troubleshooting | docs/mcp-troubleshooting.md |
| Benchmarks | benchmarks/README.md |
All commits require a DCO Signed-off-by: line. All code in English. Apache-2.0 SPDX headers on new files. See CODE_OF_CONDUCT.md and docs/development.md.
cargo fmt --all --check
cargo test --workspace
cargo build --workspaceIssues and discussions: GitHub Issues. Pull requests welcome.
Apache-2.0. See LICENSE.
Artesian stands on the shoulders of prior work. Artesian reuses ideas and APIs where appropriate, not third-party source code.
- Andrej Karpathy — the "LLM wiki" pattern — the LLM-maintained markdown knowledge base (
index.md+log.md+ entity pages; ingest/query/lint) that directly informs Artesian's Files/headwater backend and consolidation roadmap. - TencentDB Agent Memory — L0–L3 tiering, hybrid BM25+vector RRF, node_id drill-down, sqlite-vec local-first; informs
SqliteVecBackend. - Qdrant — vector store;
QdrantBackendviaQdrantVectorStore. - Google Open Knowledge Format (OKF) — Google Cloud
knowledge-catalog(Apache-2.0) — the adjacent organizational-knowledge markdown+YAML format Artesian's headwater files intentionally align with where useful. - ACC model — Bousetouane, AI Agents Need Memory Control Over More Context, arXiv:2601.11653 — the model
headgateimplements. - MemoryArena — arXiv:2602.16313 — the "recall ≠ use" framing and agentic eval methodology.
- OpenAI / Anthropic — Codex Memories, Claude Code Agent Memory, and agent loop documentation — memory model and loop framing.
- ApX Machine Learning — Agentic LLM Systems & Memory Architectures — educational reference; underlying techniques grounded in primary sources cited per-topic in
docs/. - h5i — AI-aware Git sidecar; its typed agent-handoff messaging informs Artesian's orchestration handoff protocol.
Prior art also includes Cursor scaling-agents, OpenAI Symphony, and self-correcting long-running agent patterns. All acknowledgments are references to public ideas/APIs; no third-party content is reproduced.