GitHub - ctxvault/ctxvault: Local source of truth for carrying AI work across sessions and tools.

Know what your AI tools see.

CtxVault is the local trust layer for AI work. It turns local project sources into safe, receipt-backed handoffs for AI tools, agents, coding workflows, and future API surfaces. It preserves the decisions, constraints, and working state that should survive across agents, editors, command-line sessions, and other AI work surfaces.

v0.4.0 packages the deterministic context handoff path as a complete local trust-and-handoff release. The public core still centers on local source extraction, context selection, receipt inspection, and projection before context reaches AI tools:

local sources -> context-extract -> context slices -> privacy and quality receipts -> gated projection -> receipt inspection

The baseline is intentionally constrained: no model call, no embedding service, no vector database, no remote provider. The value is that the operator can see which sources were imported, which local context was selected, why it was allowed or blocked, how large it is, and which receipt links it to an AI work surface.

The roadmap treats this as AI work quality infrastructure: specs define what "done" means, context receipts explain what was selected or blocked, and trace or runtime receipts can later inspect how AI work happened. v0.4.0 adds a static Receipt/Trust Gallery and clearer demo/review materials while keeping optional Workbench UX and native wrapper source outside the open-core package.

This public repository exposes the deterministic trust floor behind that source-to-context-to-projection loop:

local file-backed objects and rebuildable indexes
CLI and MCP entry points over the same deterministic core
review-gated promotion and projection receipts
experimental compiled workstream state with source refs
deterministic context slicing and local context search
source-grouped context selection with token budget previews
one-command local extraction from static source exports and Markdown vaults
stable source fingerprints and idempotency keys for extraction runs
deterministic context-quality, density, retrieval-gain, source-retention, search-trace, and source-conflict receipts
selected-slice privacy preflight before projection
projection receipts linked to context-selection receipts
human-readable receipt inspection for extract, selection, privacy, quality, and projection chains
owner-operated public review pack with reusable public-source scenarios, boundary checks, and a synthetic blocked-selection check
read-only doctor diagnostics and projection healthchecks
Markdown-vault import as source material
review-gated logical purge for derived slice, search, preview, and selected projection data
public schemas, fixtures, and deterministic tests

Official Project

This repository is the maintainer-controlled public core for ctxvault.

Official releases, schemas, fixtures, and compatibility checks are published only through maintainer-controlled CtxVault channels. Forks and integrations are welcome under the Apache-2.0 core license, but unofficial builds should use distinct names and should not imply maintainer endorsement.

This repository contains the public deterministic core. Optional product surfaces and maintainer release operations remain outside this repo.

What To Inspect First

If you are evaluating the project, start with:

the Quick Start below for a clean deterministic run;
spaces/huggingface/v032-deterministic-demo/ for the toy-source demo;
scripts/run_v032_deterministic_demo.py for the offline demo loop;
scripts/inspect_v032_demo_receipts.py for receipt-chain inspection;
scripts/run_v032_selection_scorecard.py for lightweight selection quality and safety checks;
scripts/run_v033_public_review_pack.py for owner-operated public package review before publication;
scripts/run_v034_context_extract_stability.py for one-click extraction stability checks;
scripts/run_v034_context_quality_scorecards.py for deterministic context quality checks.
release/v0.4.0/receipt-trust-gallery/ for static selected, omitted, blocked, privacy, projection, and proof receipt examples;
release/v0.4.0/receipt-trust-gallery/index.html for the static Receipt/Trust Gallery page;
release/v0.4.0/trials/controlled-trial-record.template.md for non-author controlled trial records;
docs/v0.4.0-release-notes.md for the complete local trust-and-handoff release scope.

Scope

The public core is for developers who want to inspect or build on:

reviewed context organization around workstreams
context projection into practical AI working surfaces
local context storage and rebuildable indexes
deterministic review-gated promotion flows
local privacy and policy gates
artifact and receipt surfaces
early source-of-truth and evidence semantics for future AI work quality contracts
compiled current workstream state with source refs
local context slice rebuild, search, and selected-slice preflight
explicit logical purge of derived data without a secure-wipe claim
Markdown-vault import as source material
read-only projection adapter healthchecks
optional local snapshot/replica backup writes
deterministic context extraction from static local exports
receipt inspection for human review before sharing context

The public core currently marks these contracts as experimental:

src/ctxvault/intelligence.py
Episode
Workstream
compiled workstream state read model
doctor report
plugin manifest and projection receipt contracts
the first local plugin executor paths for reviewed context projection targets
projection adapter healthchecks
runtime event receipts
context selection receipts
context extraction receipts
context quality and scorecard receipts

Experimental means useful and inspectable, but not yet frozen as long-term public semantics.

v0.3.5 First-Run UX Boundary

v0.3.5 records the private Workbench UX patch over v0.3.4. The Workbench can make first-run extract and inject easier for the maintainer-operated product surface, but the public open-core package does not ship that UI and does not claim runtime control.

The public boundary for this release is:

CtxVault prepares receipt-backed handoff context
agent runtimes such as Codex or Claude Code remain user-controlled
no running session is attached, controlled, inspected, or impersonated
demo data is explicit fixture seeding, not automatic private-data import
Git worktree creation, SSE progress, and runtime inventory remain roadmap items, not shipped public behavior

v0.3.4 Context Extract And Quality Receipts

v0.3.4 is a release-experience cut over the safe handoff path. It does not add model, embedding, vector, remote provider, official plugin, live connector, or public Workbench dependencies. It makes the first useful trial shorter:

run context-extract --dry-run to fingerprint sources and preview imports without writing governed objects
run context-extract to import static local sources, rebuild slices, prepare context, and optionally project when the handoff is ready
inspect the newest receipt chain with receipt-inspect --latest --summary
verify stale source fingerprints, missing selection receipts, projection links, and blocked extraction runs with read-only doctor
run deterministic quality and stability scorecards before making public quality claims
keep projection gated by handoff_ready, privacy preflight, and token-budget checks

v0.3.3 Safe Context Handoff

v0.3.3 is a hardening release over the v0.3.2 composer. It does not add model, embedding, vector, remote provider, official plugin, live connector, or public Workbench dependencies. It makes the public path easier to verify:

run the public review pack from reusable public-source scenario fixtures
prepare exact local slices with context-prepare
inspect selection_status, handoff_ready, budget state, warnings, blocked reasons, and receipt paths
project approved selected slices with context-project
verify the projection receipt and linked context-selection receipt
confirm the synthetic secret fixture is withheld and blocks projection when explicitly selected

v0.3.2 Context Selection Composer

v0.3.2 is a fast-follow release after v0.3.1. It does not add model, embedding, vector, remote provider, official plugin, or live connector dependencies. It adds the deterministic step that should happen before context is projected into an AI work surface: choose exact local slices, inspect the budget, run privacy preflight, and keep the receipt chain.

source-grouped local context candidate composition
explicit multi-slice selection
token budget preview
target-aware privacy preflight for selected slices
ctxvault.context-selection-receipt/v1
projection receipts linked to context selection receipts
local pin, hide, and archive preferences for slice suggestions
CLI and MCP tools over the same deterministic core

v0.3.1 Local Safety And Context Slicing

v0.3.1 keeps the v0.3 source-to-context-to-projection path and adds the local safety substrate needed for safer context selection:

import project docs, sessions, and Markdown notes
organize them around reviewed Workstream state
compile current truth, open questions, decisions, warnings, and source refs
rebuild deterministic local context slices from governed sources
search slices locally without model, embedding, remote service, or hosted API
run privacy preflight before selected slices are projected
project that state into AGENTS.md, CLAUDE.md, and a workstream brief
inspect projection receipts, privacy preflight receipts, logical purge receipts, tombstones, and read-only diagnostics

This is the same source-to-context-to-projection loop from M1, now made denser with compiled current state and explicit health visibility.

CtxVault remains a local context layer for AI work, not a single-harness memory plugin. ChatGPT, Claude.ai, DeepSeek, local Ollama-style UIs, Claude Code, Codex, Cursor, shell traces, project notes, and rules files can all be source or target surfaces over time. Current named-source support is explicit: normalized transcript import where stable, and experimental adapters only where marked as such.

Quick Start

Run deterministic checks:

python3 scripts/run_deterministic_checks.py

Run the v0.3.4 one-click context handoff trial:

export PYTHONPATH=src
export CTXVAULT_TRIAL=/tmp/ctxvault-v034-trial

python3 -m ctxvault.cli init-vault --root "$CTXVAULT_TRIAL"
python3 -m ctxvault.cli seed-fixtures --root "$CTXVAULT_TRIAL"

python3 -m ctxvault.cli context-extract   --root "$CTXVAULT_TRIAL"   --source-path fixtures/v0.3.4-context-extract/markdown-vault   --source-kind markdown-vault   --recursive   --prepare-query "stable one click extraction privacy projection receipts"   --workstream-ref workstream://ws_20260421_ctxvault_schema   --workstream-id ws_20260421_ctxvault_schema   --project-target workstream-brief

python3 -m ctxvault.cli receipt-inspect --root "$CTXVAULT_TRIAL" --latest --summary
python3 -m ctxvault.cli doctor --root "$CTXVAULT_TRIAL"

Run the v0.3.4 deterministic quality and stability scorecards:

python3 scripts/run_v034_context_extract_stability.py --root /tmp/ctxvault-v034-stability
python3 scripts/run_v034_context_quality_scorecards.py --root /tmp/ctxvault-v034-quality

Run the v0.3.3 public package review pack:

python3 scripts/run_v033_public_review_pack.py --root /tmp/ctxvault-v033-public-review --force

Start with the generated human report:

/tmp/ctxvault-v033-public-review/artifacts/v0.3.3-public-review/owner-review.md
/tmp/ctxvault-v033-public-review/artifacts/v0.3.3-public-review/owner-review.html

Run the clean-user core validation flow:

bash scripts/run_clean_user_core_validation.sh /tmp/ctxvault-clean-verify

Run the v0.3.2 deterministic demo:

python3 scripts/run_v032_deterministic_demo.py --root /tmp/ctxvault-v032-demo
python3 scripts/inspect_v032_demo_receipts.py --root /tmp/ctxvault-v032-demo
python3 scripts/run_v032_selection_scorecard.py --root /tmp/ctxvault-v032-scorecard

Emit reviewed context projections:

PYTHONPATH=src python3 -m ctxvault.cli emit-agents-projection --root /tmp/ctxvault-clean-verify --workstream-id ws_20260421_ctxvault_schema --output-path exports/AGENTS.md --receipt-output-path artifacts/agents-md-receipt.json
PYTHONPATH=src python3 -m ctxvault.cli emit-claude-projection --root /tmp/ctxvault-clean-verify --workstream-id ws_20260421_ctxvault_schema --output-path exports/CLAUDE.md --receipt-output-path artifacts/claude-md-receipt.json
PYTHONPATH=src python3 -m ctxvault.cli emit-wiki-projection --root /tmp/ctxvault-clean-verify --workstream-id ws_20260421_ctxvault_schema --output-path exports/workstream.md --receipt-output-path artifacts/workstream-md-receipt.json

Build compiled workstream state:

PYTHONPATH=src python3 -m ctxvault.cli compiled-workstream-state --root /tmp/ctxvault-clean-verify --workstream-id ws_20260421_ctxvault_schema

Import a Markdown vault as source material:

PYTHONPATH=src python3 -m ctxvault.cli markdown-vault-import --root /tmp/ctxvault-clean-verify --vault-path /path/to/notes --scope-kind project --scope-value ctxvault

Run read-only diagnostics:

PYTHONPATH=src python3 -m ctxvault.cli doctor --root /tmp/ctxvault-clean-verify

Rebuild and search deterministic local context slices:

PYTHONPATH=src python3 -m ctxvault.cli context-slice-rebuild --root /tmp/ctxvault-clean-verify
PYTHONPATH=src python3 -m ctxvault.cli context-search --root /tmp/ctxvault-clean-verify --query "projection receipts"

Run selected-slice privacy preflight before projecting a slice into a target:

PYTHONPATH=src python3 -m ctxvault.cli context-selection-preflight --root /tmp/ctxvault-clean-verify --slice-ref SLICE_REF --target-kind agents-md --write-receipt

Compose selected local slices with a budget preview and a selection receipt:

PYTHONPATH=src python3 -m ctxvault.cli context-selection-compose --root /tmp/ctxvault-clean-verify --query "projection receipts" --target-kind harness.agents-md --slice-ref SLICE_REF --token-budget 1200 --write-receipt

Prepare and project a safe context handoff:

PYTHONPATH=src python3 -m ctxvault.cli context-prepare --root /tmp/ctxvault-clean-verify --query "projection receipts" --target-kind harness.agents-md --token-budget 1200 --write-receipt
PYTHONPATH=src python3 -m ctxvault.cli context-project --root /tmp/ctxvault-clean-verify --target workstream-brief --workstream-id ws_20260421_ctxvault_schema --slice-ref SLICE_REF --output-path exports/workstream.md --receipt-output-path artifacts/workstream-md-receipt.json

Pin, hide, or archive local slice suggestions:

PYTHONPATH=src python3 -m ctxvault.cli context-slice-preference-set --root /tmp/ctxvault-clean-verify --slice-ref SLICE_REF --action pin --target-kind harness.agents-md

Plan a review-gated logical purge of derived data:

PYTHONPATH=src python3 -m ctxvault.cli logical-purge-plan --root /tmp/ctxvault-clean-verify --slice-ref SLICE_REF --include-projections

Run read-only projection adapter healthchecks:

PYTHONPATH=src python3 -m ctxvault.cli adapter-healthcheck --root /tmp/ctxvault-clean-verify --target-kind agents-md --target-path exports/AGENTS.md
PYTHONPATH=src python3 -m ctxvault.cli adapter-healthcheck --root /tmp/ctxvault-clean-verify --target-kind claude-md --target-path exports/CLAUDE.md
PYTHONPATH=src python3 -m ctxvault.cli adapter-healthcheck --root /tmp/ctxvault-clean-verify --target-kind workstream-brief --target-path exports/workstream.md

Write an optional local snapshot/replica backup to an explicit local target:

PYTHONPATH=src python3 -m ctxvault.cli local-backup-write --root /tmp/ctxvault-clean-verify --target file:///tmp/ctxvault-clean-verify-backup --label "local backup rehearsal" --device-id local-target

Inspect the default runtime layout:

PYTHONPATH=src python3 -m ctxvault.cli print-layout

Initialize a local vault:

PYTHONPATH=src python3 -m ctxvault.cli init-vault

Run the stdio MCP transport:

PYTHONPATH=src python3 -m ctxvault.cli serve-mcp

M1 Projection Evidence

Run the source-to-projection golden path:

python3 scripts/run_context_injection_m1_golden_path.py --root /tmp/ctxvault-m1-context-injection

The checked-in M1 fixture evidence is in:

fixtures/context-injection-m1/projections/AGENTS.md
fixtures/context-injection-m1/projections/CLAUDE.md
fixtures/context-injection-m1/projections/workstream-brief.md
fixtures/context-injection-m1/projections/agents-md-receipt.json
fixtures/context-injection-m1/projections/claude-md-receipt.json
fixtures/context-injection-m1/projections/workstream-brief-receipt.json
fixtures/m1-context-injection/README.md

v0.4.0 Evidence

The v0.4.0 local trust-and-handoff release, v0.3.5 first-run UX boundary, v0.3.4 context extraction path, v0.3.3 safe handoff path, v0.3.2 context-selection composer, v0.3.1 local safety, and compiled context projection evidence are described in:

docs/v0.3-compiled-context.md
docs/v0.4.0-release-notes.md
release/v0.4.0/receipt-trust-gallery/index.html
release/v0.4.0/receipt-trust-gallery/README.md
release/v0.4.0/receipt-trust-gallery/manifest.json
release/v0.4.0/trials/controlled-trial-record.template.md
docs/v0.3.5-release-notes.md
docs/v0.3.4-release-notes.md
docs/v0.3.3-release-notes.md
fixtures/v0.3.4-context-extract/README.md
fixtures/v0.3.3-public-review/README.md
docs/v0.3.2-release-notes.md
docs/v0.3.2-injection-composer/implementation-plan.md
docs/v0.3.2-injection-composer/experimental-schemas/ctxvault-context-selection-receipt-v1.schema.json
docs/v0.3.1-release-notes.md
docs/v0.3.1-local-safety/approved-boundary-decisions.md
docs/v0.3.1-local-safety/hardening-status.md
docs/v0.3-release-notes.md
docs/v0.2-m2-developer-framework.md
docs/v0.2-m2-compatibility-evidence.md
docs/v0.2-m2-release-notes.md

The local backup write path is optional local durability. It creates a governed snapshot, copies the snapshot manifest, restore bundle, and sync manifest into an explicit local target, and verifies the target as a replica before reporting success. It does not make a hosted service the source of truth and does not replace a separate offsite backup strategy.

Public Docs

docs/public-core-boundary.md
docs/public-release-checklist.md
docs/experimental-contract-evolution-policy.md
docs/workstream-plan-ledger-contract.md
docs/v0.3-compiled-context.md
docs/v0.4.0-release-notes.md
release/v0.4.0/receipt-trust-gallery/index.html
release/v0.4.0/receipt-trust-gallery/README.md
release/v0.4.0/receipt-trust-gallery/manifest.json
release/v0.4.0/trials/controlled-trial-record.template.md
docs/v0.3.5-release-notes.md
docs/v0.3.4-release-notes.md
docs/v0.3.3-release-notes.md
docs/v0.3.2-release-notes.md
docs/v0.3.2-injection-composer/implementation-plan.md
docs/v0.3.1-release-notes.md
docs/v0.3.1-local-safety/approved-boundary-decisions.md
docs/v0.3.1-local-safety/hardening-status.md
docs/v0.3-release-notes.md
docs/v0.2-m2-developer-framework.md
docs/v0.2-m2-compatibility-evidence.md
docs/v0.2-m2-release-notes.md
fixtures/v0.3.4-context-extract/README.md
fixtures/v0.3.3-public-review/README.md
fixtures/README.md
schemas/README.md
CHANGELOG.md
TRADEMARK.md

Feedback

The most useful feedback is concrete: what you ran, what confused you, and which receipt, slice, projection, or workflow step was hard to trust.

Feedback is separated by evidence level:

ordinary issues are for bugs, wording gaps, install friction, and general trust questions;
first 10 minutes trial reports capture the first activation path and the first blocker, but may be self-reported;
non-author controlled trial evidence uses release/v0.4.0/trials/controlled-trial-record.template.md and is the only feedback category that can support later public beta readiness claims.
v0.3 Compiled Context feedback: .github/ISSUE_TEMPLATE/workflow-pain-point.yml
v0.3.1 local safety, privacy, or purge feedback: .github/ISSUE_TEMPLATE/trust-or-privacy-concern.yml
v0.3.2 context-selection composer feedback: .github/ISSUE_TEMPLATE/workflow-pain-point.yml
v0.3.3 safe context handoff feedback: .github/ISSUE_TEMPLATE/workflow-pain-point.yml
v0.3.5 first-run UX boundary feedback: .github/ISSUE_TEMPLATE/workflow-pain-point.yml
v0.4.0 First-Run Feedback: .github/ISSUE_TEMPLATE/v0.4.0-first-run-feedback.yml
v0.4.0 First 10 Minutes Trial Report: .github/ISSUE_TEMPLATE/v0.4.0-first-10-minutes-trial.yml
v0.4.0 Non-Author Controlled Trial Record: release/v0.4.0/trials/controlled-trial-record.template.md
Mac App Alpha feedback: .github/ISSUE_TEMPLATE/mac-app-alpha-feedback.yml
v0.2/M2 Developer Framework Feedback: .github/ISSUE_TEMPLATE/v0.2-m2-feedback.yml
M1 Quick Feedback: .github/ISSUE_TEMPLATE/m1-quick-feedback.yml
workflow friction: .github/ISSUE_TEMPLATE/workflow-pain-point.yml
trust or privacy concerns: .github/ISSUE_TEMPLATE/trust-or-privacy-concern.yml
broader positioning or adapter discussion: GitHub Discussions

License

Apache-2.0. See LICENSE.

Trademark and official-project usage guidelines are in TRADEMARK.md.

推荐订阅源

Hacker News: Show HN