Demo paper · IEEE BigData 2026 · AAI-BD workshop
Agent memory you can audit.
contextctl manages what AI agents remember as governed data: markdown concept files in an open format, Git as the write gate and the transaction-time record, a content-addressed evidence folder, and a rebuildable SQLite sidecar with SCD Type 2 history.
$ contextctl curate # validate + reconcile staged drafts
$ contextctl review approve ID --resolve '{"expr": "is true"}'
$ contextctl merge # git merge --no-ff = one snapshot
$ contextctl history concepts/measures/food_revenue.md \
--field expr --valid-at 2024-06-01
"case when is_food_item = 1 then product_price else 0 end"
The problem
During a migration, an incident-response agent learns that a critical pipeline belongs to an engineer who has left, and routes alerts to nobody for three weeks. Operators cannot say when it learned this, from what source, what it believed before, or how to restore the correct state with proof.
Common memory services keep facts in vendor schemas, keep no content-hash link to the source, and accept agent writes without review. contextctl targets four properties together:
- Custodyof the source bytes behind each belief, by SHA-256.
- Authorizationan explicit review step before machine-written knowledge becomes trusted.
- Reconstructionof what was believed, and when, on two time axes.
- Minimal contextserving only what a task needs, by progressive disclosure.
No single mechanism is new; the combination is the point.
Four layers, one job each
Generation is untrusted. Curation is the only path into trusted state. The sidecar is a cache you can delete and rebuild. Serving may only propose writes, which re-enter staging.
- Evidence object
- Connectors store the raw bytes at
evidence/<h>, wherehis the SHA-256 of those bytes only. A retried fetch is idempotent; an edited source becomes a new object and the old one is kept. - OKF-MEM header
- Concepts are markdown files in the Open Knowledge Format with memory fields:
actor,evidence,sources,confidence,supersedes, and validity dates. - Write gate
- Admission is a
git merge --no-ffinto main. Every merge is a snapshot: the transaction-time record.
Reconciliation: dedupe before a human sees it
Each draft is compared with the top-10 full-text matches and the same-path concept, using TF-IDF cosine similarity and the fact fields both assert with different values. Provenance fields never raise a conflict. The first matching rule applies.
a fact field differs from the same-path concept
Show both values; a human resolves; supersedes is recorded.
max sim ≥ 0.9 and no new facts
Drop the draft and log the match.
0.5 ≤ max sim < 0.9
Rewrite as an edit of the best match.
max sim < 0.5
Add as a new concept.
A Duplicate or Revision whose best match is a different concept (a rename or a sibling) is held for review rather than applied.
As-of reads on two time axes
A post-merge hook maintains one SQLite file: an SCD Type 2 belief_history table over header fields and a body digest, an FTS5 index and a link table. Valid time comes from headers; transaction time comes from Git.
“What was the expression on t?” is one range query:
SELECT new_value FROM belief_history
WHERE concept = :c AND field = 'expr'
AND valid_from <= :t
AND (valid_to IS NULL OR valid_to > :t);
“What did the bundle say then?” is an as-of read at that snapshot: contextctl read PATH --as-of 2024-08-01. With a retroactive valid_from, the two answers differ exactly over the period in which the agent was wrong.
| old | new | valid_from | valid_to |
|---|---|---|---|
| – | = 1 | 2023-08-30 | 2024-09-12 |
= 1 | is true | 2024-09-12 | 2025-07-01 |
is true | bare boolean | 2025-07-01 | open |
The standing test: delete the sidecar, rebuild it from Git, and compare a canonical row dump.
Results
Measured in the paper on the built core with no language model: storage, versioning, indexing and the gate. They show the substrate works; they are not evidence for accuracy, token savings or the proposed integrity properties.
git showWhat the replay taught us
- (a) Checking Conflict against every candidate flagged 359 of 373 drafts, so Conflict is scoped to the same path.
- (b) A coordinated header-and-blob rewrite passed the digest check and showed only as an uncommitted Git change.
- (c) The full governed bundle cost about 4.6× the tokens of the raw sources: digests and URIs tokenize poorly.
- (d) Reverting one merge conflicted with a later merge of the same files.
Reproduced with this repository
Reproduced (this implementation) A clean re-implementation from the paper's text, re-run on a fully synthetic project and on the same public dbt history. Counts differ from the paper because the harvester's scope is our reading of the text; the checks and the worked example match.
| Metric | Paper | Synthetic replay | Public dbt replay |
|---|---|---|---|
| Source steps | 25 | 25 | 23 |
| Drafts | 373 | 531 | 764 |
| New / Duplicate / Revision / Conflict | 16 / 322 / 24 / 11 | 21 / 488 / 7 / 15 | 35 / 707 / 9 / 13 |
| Final concepts | 22 | 25 | 43 |
| As-of reads matching git show | 665/665 | 362/362 | 302/302 |
| Rebuilt sidecar = incremental | yes | yes | yes |
| Identical repeats | 7/7 | 7/7 | 7/7 |
| Full bundle / raw tokens | 4.6× | 4.09× | 1.9× |
| Appendix B food_revenue rows | 3 rows: 2023-08-30 → 2024-09-12 → 2025-07-01 | 3 rows: 2023-08-30 → 2024-09-12 → 2025-07-01 | 3 rows: 2023-08-30 → 2024-09-12 → 2025-07-01 |
Every number in this table comes from examples/reproduce_paper.py (results in examples/results/). Timings depend on hardware.
Quickstart
Python 3.10+, Git and SQLite (with FTS5, standard in CPython). No services and nothing paid.
git clone https://github.com/AyanPutatunda/contextctl.git
cd contextctl
python -m venv .venv && . .venv/bin/activate
pip install -e '.[tokens]'
contextctl selfcheck # nine-check lifecycle
bash examples/quickstart.sh # four layers on synthetic notes
contextctl replay --repeats 3 # replay harness, deterministic
The repository is private for now; access on request.
Day-to-day CLI
contextctl init
contextctl ingest notes/ # generation (untrusted)
contextctl curate # validate + reconcile
contextctl review list
contextctl review approve ID [--resolve '{...}']
contextctl merge # git merge --no-ff
contextctl orient | search Q | read PATH [--as-of T]
contextctl history PATH --field F --valid-at T
contextctl provenance PATH # concept→commit→evidence→source
contextctl sidecar check # delete + rebuild + compare
Paper
contextctl: Auditable, Open-Format Context Infrastructure for AI Agents
Demo paper, AAI-BD workshop at the 2026 IEEE International Conference on Big Data (BigData 2026).
AI agents act on remembered facts, yet common memory services keep those facts in vendor schemas, keep no content-hash link to the source, and accept agent writes without review. We demonstrate contextctl, which manages agent context as governed data: markdown concept files in the Open Knowledge Format (OKF), Git as write gate and transaction-time record, a content-addressed evidence folder, and a rebuildable SQLite sidecar holding SCD Type 2 history. The demo runs the storage, versioning, indexing, and a minimal review gate with no language model, including a replay of a public dbt project's history.
Cite
@inproceedings{putatunda2026contextctl,
title = {contextctl: Auditable, Open-Format Context Infrastructure for AI Agents},
author = {Putatunda, Ayan and Jangoan, Suhas},
booktitle = {2026 IEEE International Conference on Big Data (BigData),
AAI-BD Workshop},
year = {2026},
note = {Demo paper},
url = {https://contextctl.sh}
}