Session state
Where is this task right now?
Useful for continuing one workflow across prompts or handoffs.
Case study · ContextVault v0.1.0
Governed memory for agentic software work.
ContextVault is a local memory prototype for long-running multi-agent coding work. It keeps architectural decisions, preferences and warnings current across sessions, with citations and receipts for the context an agent used.
Typed records and governed writes flow through a local memory service into budgeted memory packs for CLI, HTTP and MCP adapters.
Problem
Agents need several kinds of context, not one generic memory.
In long-running software work, the failure mode is not only that an agent cannot find information. It can also find old information and treat it as current.
Repo context
How does this codebase work?
AGENTS.md, README files and generated repo wikis help the agent orient inside one repository.
Cross-repo context
Which repositories matter?
A catalog tells the agent what related projects, standards and source-of-truth files to inspect.
Governed memory
What is currently valid?
This is the ContextVault layer: current decisions, stale warnings, superseded records and auditable context use.
Design choice
The problem changes when many agents work across many sessions.
A Markdown note or ADR log is often enough for a small project. A repo wiki helps an agent understand one codebase. A catalog helps with cross-repo navigation.
ContextVault sits between those lightweight patterns and an enterprise context platform. It is for work where architectural alignment matters, but a full internal developer portal would be too heavy.
The prototype asks a narrower question: can a local memory layer tell an agent which decision is current, which record is stale, what superseded what, and why a piece of context was selected?
Implementation
What the prototype includes.
Memory model
- Typed Markdown records for facts, preferences, decisions, source notes and warnings.
- Temporal metadata: recorded_at, valid_from and valid_until.
- Supersedes and contradicts relations for deterministic truth resolution.
Governance
- Session writes pass through allow, redact, quarantine or block outcomes.
- Memory packs include source citations and one-hop relations.
- Receipts are generated from metadata-only traces, not raw task text.
Release surface
- Python CLI and HTTP API share the same service path.
- Docker image runs as a non-root user with a persistent data volume.
- Read-only FastMCP adapter exposes context, memories, relations and receipts.
Governed memory ladder
Where ContextVault fits.
Tier 0
Prompt memory. Good for one-off work; disappears across sessions.
Tier 1
Markdown notes. Useful for small projects; stale or conflicting notes remain a human problem.
Tier 2
ADRs and decision logs. Good for explicit architecture history; agents still infer what is current.
Tier 3
Structured Markdown. Adds types, dates and status; truth resolution is still mostly manual.
Tier 4
Local governed memory service. ContextVault: current memory packs, stale exclusion, write policy, citations and receipts.
Tier 5
Enterprise context platform. Ownership, permissions, compliance and organization-wide governance.
Evidence
- 47/47 automated tests
- 3/3 golden evaluation cases
- Hosted GitHub Actions passing
- Clean-clone verification completed
- Docker smoke test as non-root UID 10001
- Public v0.1.0 release
Boundaries
What this prototype intentionally does not claim.
ContextVault is not a replacement for repo documentation, ADRs, cross-repo catalogs, vector search or enterprise context platforms.
It is a local single-user portfolio prototype, not a multi-tenant production service. DuckDB is used for an embedded local store, and horizontal write scaling is explicitly out of scope.
The measured evaluation is synthetic and deterministic. It validates memory-system behavior and citation contracts, not model quality or business impact.