+memoryadapter

+memoryadapter is a standalone local reference for letting verified agents retrieve from, propose changes to, and share narrow capabilities around a human-owned Markdown/Git knowledge base without making an agent or a database the knowledge authority.

Its governing invariant is:

verified workload
→ exactly one server-side profile
→ authorized and cited retrieval
→ immutable quarantined candidate
→ curator validation
→ exact-byte human approval
→ process-safe single-writer Git promotion
→ authenticated durable receipt
→ deterministic projection rebuild

Release status: implemented_local_reference / alpha. This repository is not a production workload-attestation system, an Internet-hardened service, a full MCP conformance implementation, or proof that optional external providers enforce its authority model.

Supported scope is this local alpha only. A readiness PASS never authorizes publication, push, package upload, release creation, or deployment. No public security-reporting endpoint exists; publication is blocked until one is established. Never put secrets or live private data in an issue or report.

What it protects

Plane	Authority
Canonical knowledge	Reviewed Markdown bytes and Git history
Identity and policy	Tenant-scoped server-side profile bindings and current policy state
Workflow	SQLite state machines, immutable records, locks, and receipts outside the vault
Retrieval	Rebuildable SQLite FTS5 and deterministic explicit-link projection
Optional projections	Disabled, non-authoritative adapters for Qdrant, pgvector, and Mem0 pointers

SQLite is authoritative only for the narrow workflow and receipt records that make review and promotion durable. It is not a replacement for canonical Markdown/Git.

Implemented surfaces

• Numbered Obsidian-compatible starter vault and portable existing-vault mappings.
• Scope-first FTS5 retrieval with canonical path, source digest, Git revision, and chunk citations.
• Tenant-scoped certificate fingerprint to exactly-one-profile identity mapping.
• Unknown, expired, revoked, ambiguous, or drifted identities fail closed.
• Content-addressed candidate quarantine outside canonical search and Git.
• Server-enforced principal separation: the submitter and preparer may be the same or separate principals; the curator differs from both, the reviewer differs from all three, and the promotion operator differs from every prior actor.
• Projection rebuilds read strict UTF-8 Markdown only from binary-safe Git blob plumbing at one pinned commit; modified tracked and untracked working-tree files are never sources.
• Exact-byte, base-revision-bound, process-safe Git promotion with crash recovery.
• One durable authenticated receipt and one canonical commit per successful promotion.
• Reviewed MCP manifests and opaque, recipient-bound, one-use claim references.
• Minimal mTLS JSON-RPC surface for health, cited retrieval, context, source reads, and noncanonical candidate submission.
• OS-trusted administrative CLI with bounded JSON failures.
• Packaged, dependency-free review UI at /review/ with desktop/mobile, dark/light, keyboard, reduced-motion, empty/error, stale, expired, revoked, and hostile-content handling.
• Deterministic SQLite migration export and adversarial wheel/sdist validation.

Safety boundaries

• Exact-byte approval prevents substitution; it does not prove factual truth.
• Multi-agent agreement cannot approve or promote canonical content.
• MCP tools cannot write canonical Markdown directly.
• Local-CA mTLS is a reproducible development identity tier, not SPIFFE/SPIRE or production workload attestation.
• Local OS trust applies only to explicitly private administrative CLI paths. Agent-facing HTTP/MCP and public in-process retrieval functions require a current registered session; missing, forged, expired, or revoked sessions fail closed.
• PostgreSQL RLS is not a verified authority control in v0.1.
• Qdrant, pgvector, and Mem0-pointer integrations are disabled, network-silent, and non-authoritative unless explicitly configured and invoked.
• The wheel is designed for byte reproducibility under a fixed SOURCE_DATE_EPOCH; byte-for-byte sdist reproducibility is not claimed.
• Never place the state root or PKI directory inside the canonical vault.

See Threat model for controls and residual risks.

Requirements

• Linux or another POSIX environment
• Python 3.11 or newer
• Git
• OpenSSL CLI for the local development CA helpers
• Python's SQLite build with FTS5 enabled
• uv for development and release verification only

The runtime package has no third-party Python dependencies.

Install

From a source checkout:

python3.11 -m venv .venv
.venv/bin/python -m pip install .

For development, install the locked development group. Add the release group only when running the local scanner and release-readiness procedure:

uv sync --frozen --group dev
uv sync --frozen --group dev --group release  # release verification only

For release acceptance, use the exact-tree clean-room build and installed-artifact procedure in Local release readiness.

Synthetic proof

The demo creates only temporary synthetic data. Do not point it at a personal vault.

memoryadapter demo

A successful run proves the local reference path through quarantine, curator validation, exact-byte approval, one Git promotion, one durable receipt, deterministic rebuild, cited readback, capability review, one-use redemption, replay denial, and scoped MCP dispatch.

Safe local start

Create sibling vault, state, and PKI directories—never nest state or PKI beneath the vault:

mkdir -p ./lab
memoryadapter init ./lab/vault --state-root ./lab/state
memoryadapter status ./lab/vault --state-root ./lab/state

memoryadapter pki-init ./lab/pki
memoryadapter pki-issue ./lab/pki server localhost --server
memoryadapter pki-issue ./lab/pki reviewer localhost \
  --uri spiffe://example.test/reviewer

Register the client certificate fingerprint emitted by pki-issue under exactly one profile:

CLIENT_FINGERPRINT='<64 lowercase hexadecimal characters>'

memoryadapter profile-register ./lab/vault \
  --state-root ./lab/state \
  --audience localhost \
  --origin https://localhost:8765 \
  --principal spiffe://example.test/reviewer \
  --profile security-reviewer \
  --fingerprint "$CLIENT_FINGERPRINT" \
  --tenant example \
  --role reviewer \
  --tool memoryadapter.health \
  --prefix 05_Wiki

Start the loopback-only mTLS service:

memoryadapter serve ./lab/vault \
  --state-root ./lab/state \
  --audience localhost \
  --origin https://localhost:8765 \
  --pki-root ./lab/pki \
  --server-cert-name server \
  --host 127.0.0.1 \
  --port 8765

The server refuses non-loopback binds, non-HTTPS or mismatched origins, missing PKI material, and TLS contexts that do not require client certificates. Open https://localhost:8765/review/ only in a browser configured to present the issued client certificate.

Existing vault mapping

The mapping operation writes validated operational configuration beneath the state root; it does not move notes:

memoryadapter map ./existing-vault \
  --state-root ./state \
  examples/vault-mapping.json
memoryadapter rebuild ./existing-vault --state-root ./state

Only mapped Markdown blobs committed in the pinned Git tree are indexed. Excluded paths, attachments, working-tree-only files, operational databases, candidate objects, keys, and receipts are never canonical retrieval sources.

Documentation

• Architecture
• Operations and recovery
• Threat model
• Implementation contract
• Reuse provenance
• Local release readiness
• Contributing
• Security policy
• Support
• Changelog
• Code of conduct

Development gates

uv sync --frozen --group dev
uv run --frozen --group dev pytest -vv
uv run --frozen --group dev ruff check --no-cache .
uv run --frozen --group dev python -m compileall -q -f src scripts tests
node --check src/memoryadapter/web/app.js
uv run --frozen --group dev python scripts/sanitize.py
uv run --frozen --group dev python scripts/export_sqlite_schema.py --check
uv run --frozen --group dev python scripts/check_docs.py
uv lock --check
git diff --check

Artifact checking belongs to the index-only release procedure in Operations, not the ordinary source gate. The automated sanitizer rejects its defined high-confidence private paths, credential forms, key headers, secret assignments, forbidden filenames, and invalid UTF-8; it does not prove that arbitrary text contains no secret, so independent review remains required. The tracked clean-room harness and scanner commands are documented in Local release readiness. Generated evidence lives outside the source tree and is not a runtime artifact. Wheel byte equality is required; sdist byte reproducibility is unclaimed. Support is best effort and requires synthetic local evidence.

License

MIT. See LICENSE.