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:

  1. Custodyof the source bytes behind each belief, by SHA-256.
  2. Authorizationan explicit review step before machine-written knowledge becomes trusted.
  3. Reconstructionof what was believed, and when, on two time axes.
  4. 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>, where h is 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-ff into main. Every merge is a snapshot: the transaction-time record.
Four stacked layers: 1 Generation (untrusted), 2 Curation (trust boundary), 3 Metadata (derived SQLite sidecar), 4 Serving (propose only). Arrows go up from layer to layer; a dashed arrow from Serving returns proposals to staging.
Trusted state is layer 2: OKF files, Git history and the evidence folder. Layer 3 can be deleted and rebuilt.

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.

1 · Conflict

a fact field differs from the same-path concept

Show both values; a human resolves; supersedes is recorded.

2 · Duplicate

max sim ≥ 0.9 and no new facts

Drop the draft and log the match.

3 · Revision

0.5 ≤ max sim < 0.9

Rewrite as an edit of the best match.

4 · New

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.

Worked example: the food_revenue expression (paper, Appendix B)
oldnewvalid_fromvalid_to
–= 12023-08-302024-09-12
= 1is true2024-09-122025-07-01
is truebare boolean2025-07-01open

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.

373drafts replayed from the public dbt Jaffle Shop history
322classified Duplicate (16 New, 24 Revision, 11 Conflict)
665/665as-of reads matched git show
155 mssnapshot commit at 104 concepts (634 ms at 105)
< 1 sfull sidecar rebuild; sub-ms point-in-time queries
9/9no-model lifecycle checks passed; rebuild matched row for row

What 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.

MetricPaperSynthetic replayPublic dbt replay
Source steps252523
Drafts373531764
New / Duplicate / Revision / Conflict16 / 322 / 24 / 1121 / 488 / 7 / 1535 / 707 / 9 / 13
Final concepts222543
As-of reads matching git show665/665362/362302/302
Rebuilt sidecar = incrementalyesyesyes
Identical repeats7/77/77/7
Full bundle / raw tokens4.6×4.09×1.9×
Appendix B food_revenue rows3 rows: 2023-08-30 → 2024-09-12 → 2025-07-013 rows: 2023-08-30 → 2024-09-12 → 2025-07-013 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.

Download PDF

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}
}