Metadata-Version: 2.4
Name: memoryadapter
Version: 0.5.0
Summary: Local governed Markdown/Git knowledge authority reference
Author-email: Czarina Castillo <castilloczarina@gmail.com>
License-Expression: MIT
Keywords: markdown,knowledge,governance,mcp,vault,agents
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Security
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# +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:

```text
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 provider projections (vector stores, remote memory) built on the core pointer store |

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 PARA Markdown starter vault (YAML frontmatter + wikilink conventions, portable and editor-neutral) 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.

## Planned surfaces (roadmap)

- **Vault Studio**: an own local web UI (viewer, search, graph, staging/review
  panels) over the same Markdown vault and governed MCP surface; viewer-first,
  editor-later; the vault stays portable plain Markdown/Git. Roadmap item 11.
- **Session working memory (RAM layer) + funnel visibility** (v0.4.0 P4b):
  per-session scratch store and read-only staging view.
- **Memory lifecycle, reconcile-first** (v0.4.0 P4): conflict surfacing for
  pointers below the canonical line.

## 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 remote-memory provider projections 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](docs/THREAT_MODEL.md) 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:

```bash
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:

```bash
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](docs/LOCAL_RELEASE_READINESS.md).

## Synthetic proof

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

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](docs/ARCHITECTURE.md)
- [Operations and recovery](docs/OPERATIONS.md)
- [Threat model](docs/THREAT_MODEL.md)
- [Implementation contract](docs/IMPLEMENTATION_CONTRACT.md)
- [Reuse provenance](docs/REUSE_PROVENANCE.md)
- [Local release readiness](docs/LOCAL_RELEASE_READINESS.md)
- [Contributing](CONTRIBUTING.md)
- [Security policy](SECURITY.md)
- [Support](SUPPORT.md)
- [Changelog](CHANGELOG.md)
- [Code of conduct](CODE_OF_CONDUCT.md)

## Development gates

```bash
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](docs/OPERATIONS.md#15-componentlegacy-manual-artifact-probe), 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](docs/LOCAL_RELEASE_READINESS.md). 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](LICENSE).
