Metadata-Version: 2.4
Name: l9-graphite-memory
Version: 2.3.1
Summary: Contract-governed bi-temporal memory substrate for autonomous agents
Author: Quantum-L9
License: Proprietary
Project-URL: Homepage, https://github.com/Quantum-L9/l9-graphiti-memory
Project-URL: Repository, https://github.com/Quantum-L9/l9-graphiti-memory
Project-URL: Issues, https://github.com/Quantum-L9/l9-graphiti-memory/issues
Keywords: agent-memory,bi-temporal,graphiti,knowledge-graph,mcp,temporal-memory
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: pyyaml<7,>=6.0
Provides-Extra: server
Requires-Dist: fastapi<1,>=0.115; extra == "server"
Requires-Dist: uvicorn<1,>=0.30; extra == "server"
Provides-Extra: active
Requires-Dist: redis<7,>=5; extra == "active"
Provides-Extra: postgres
Requires-Dist: psycopg2-binary<3,>=2.9; extra == "postgres"
Provides-Extra: zep
Requires-Dist: zep-cloud<4,>=3.0; extra == "zep"
Provides-Extra: phase6
Requires-Dist: cryptography<47,>=46.0; extra == "phase6"
Requires-Dist: jsonschema<5,>=4.26; extra == "phase6"
Requires-Dist: PyJWT<3,>=2.13; extra == "phase6"
Provides-Extra: infisical
Requires-Dist: infisical-python<3,>=2.0; extra == "infisical"
Provides-Extra: all
Requires-Dist: fastapi<1,>=0.115; extra == "all"
Requires-Dist: uvicorn<1,>=0.30; extra == "all"
Requires-Dist: psycopg2-binary<3,>=2.9; extra == "all"
Requires-Dist: redis<7,>=5; extra == "all"
Requires-Dist: zep-cloud<4,>=3.0; extra == "all"
Requires-Dist: infisical-python<3,>=2.0; extra == "all"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: fastapi<1,>=0.115; extra == "dev"
Requires-Dist: uvicorn<1,>=0.30; extra == "dev"
Requires-Dist: cryptography<47,>=46.0; extra == "dev"
Requires-Dist: jsonschema<5,>=4.26; extra == "dev"
Requires-Dist: PyJWT<3,>=2.13; extra == "dev"
Requires-Dist: mypy<2,>=1.11; extra == "dev"
Requires-Dist: pytest<10,>=8.3; extra == "dev"
Requires-Dist: pytest-cov<7,>=5; extra == "dev"
Requires-Dist: pytest-asyncio<1,>=0.23; extra == "dev"
Requires-Dist: psycopg2-binary<3,>=2.9; extra == "dev"
Requires-Dist: httpx2<3,>=2.12; extra == "dev"
Requires-Dist: ruff<1,>=0.8; extra == "dev"
Dynamic: license-file

<!-- L9_META
l9_schema: 1
repo: Quantum-L9/l9-graphiti-memory
path: README.md
layer: repository
owner: memory-control-plane
status: active
version: 2.3.0
updated: 2026-07-27
/L9_META -->

# L9 Graphiti Memory

Contract-governed, bi-temporal memory for autonomous agents.

Version 2.1 is the recursive convergence release for `Quantum-L9/l9-graphiti-memory`. It preserves valid package, CLI, MCP, and hook surfaces while replacing the old provider-centered internals with one authorized `MemoryService`, one canonical record store, typed evidence receipts, explicit temporal coordinates, and rebuildable graph or semantic projections.

The repository name uses **Graphiti** because the project integrates with Graphiti-style graph memory. The published distribution and Python import remain `l9-graphite-memory` and `l9_graphite_memory` for compatibility. See ADR-058.

## Guarantees

- One canonical durable write path
- Server-derived principals and namespace authorization
- Versioned memory taxonomy and schema upcasting
- Valid-time plus transaction-time queries
- Deterministic admission, quarantine, idempotency, and supersession
- Evidence-bound atomic extraction and offline source distillation
- Consent-governed identity and preference memory
- Bounded hydration with explainable ranking
- Independent graph, semantic, lexical, and temporal retrieval evidence
- Atomic core commit plus durable projection outbox
- Persistent provider locators for verified projection erasure
- Governed promotion, retention, lineage replay, and procedural candidates
- Explicit complete, partial, failed, duplicate, rejected, quarantined, archived, and deleted outcomes
- No plaintext secret persistence in generated agent configuration
- Installed-wheel operation without a source checkout
- A machine-validated 69-ADR ledger and 44-decision harvest coverage map

## L9 alignment boundary

This repository is a dependency package, not a runnable constellation node. Internal operations use typed memory contracts. L9 inter-node consumers inject the canonical TransportPacket factory and Gate client through `GateMemoryBridge`; the package never defines the shared packet model or resolves destinations. Optional editor hooks use a local receipt guard, not a second Gate. See [`ALIGNMENT.md`](ALIGNMENT.md).

## Architecture

```text
CLI / MCP / Python SDK / compatibility hooks
                    |
           authenticated principal
                    |
               MemoryService
  authorize -> normalize -> validate -> admit -> commit -> receipt
                                      |
                         canonical RecordStore
                                      |
                       atomic durable outbox
                                      |
                    optional projections
                 Graphiti MCP / Zep / none
```

The canonical SQLite store is fully functional without Zep, Neo4j, PostgreSQL, Redis, LangGraph, or an LLM. Optional providers are projections, not sources of truth.

## Install

Checkout-based development uses **uv** with the committed lockfile (ADR-069):

```bash
# https://docs.astral.sh/uv/getting-started/installation/
uv sync --frozen --no-install-project --no-build --extra dev --extra server
source .venv/bin/activate   # or prefix commands with: uv run
```

Or: `bash scripts/install.sh` (requires `uv`).

Published distribution consumers (no checkout) may still use pip:

```bash
python -m pip install l9-graphite-memory
python -m pip install 'l9-graphite-memory[server,zep]'
```

## Quick start

```bash
export L9_MEMORY_PROJECTION_BACKEND=none
l9-memory resolve
l9-memory health
l9-memory write 'Always run contract tests before merge' \
  --kind decision \
  --group-id l9-graphiti-memory \
  --source operator
l9-memory search 'contract tests' --group-id l9-graphiti-memory
```

Sensitive profile writes require purpose-bound consent evidence. Verified deletion requires administrator authority, a reason, and a verification reference.

## Command surface

```text
health, resolve, write, search, hydrate, get, stats, conflicts,
phase-lock, verify-phase-lock, lineage, bootstrap, import, distill,
inject, autoseed-check, prune, promote, delete,
synthesize-procedures, maintain, rebuild-projection, outbox-run,
drain-legacy-write-queue, ingest-topology-plan
```

Legacy MCP aliases `write`, `search`, `health`, `bootstrap`, `phase_lock`, and `conflicts` remain thin adapters to canonical `memory.*` handlers.

## Configuration

Copy `config/memory.yaml.example` and set `L9_MEMORY_CONFIG` to its path. Environment variables override YAML. Cursor and Claude config writers persist commands and non-secret settings only. Cursor instantiation is governed by the canonical `l9-memory client cursor` lifecycle (`inspect`, `install`, `verify`, `status`, `uninstall`); see `docs/CURSOR_INSTANTIATION.md` and ADR-064.

Canonical store choices:

- `sqlite` (default): a single-process local ledger. Not a distributed authority — only processes that can open the file share the memory.
- `postgres`: the shared backend for multi-agent and scheduled deployments. Requires `L9_MEMORY_POSTGRES_DSN` and the `postgres` extra (`pip install 'l9-graphite-memory[postgres]'`). See ADR-072.

Projection choices:

- `none`: canonical standalone memory only
- `http`: official or legacy Graphiti MCP projection
- `zep`: Zep Cloud graph projection through `zep-cloud`

The HTTP adapter discovers the live Graphiti tool inventory. It supports the current `add_memory`, `search_memory_facts`, `search_nodes`, and `delete_episode` dialect plus the older `add_episode` and `search_facts` compatibility dialect.

## Validation

```bash
pytest -q
python tools/assurance/validate_harvest_coverage.py
python tools/assurance/validate_adrs.py
bash scripts/preflight.sh
bash scripts/validate_release.sh
```

`validate_release.sh` builds and installs the wheel, runs installed-package smoke checks, and writes evidence under `validation/`. Live provider, production migration, hosted CodeQL, branch-protection, and credential-rotation proofs remain external release gates.

## Documentation

- [Architecture](ARCHITECTURE.md)
- [Runbook](RUNBOOK.md)
- [Migration](MIGRATION.md)
- [Security](SECURITY.md)
- [Recursive harvest audit](docs/RECURSIVE_HARVEST_AUDIT.md)
- [Machine-readable harvest coverage](docs/harvest_coverage.yaml)
- [Harvest map](docs/HARVEST_MAP.md)
- [Remediation and integration register](docs/REMEDIATION_AND_INTEGRATION_PLAN.md)
- [Compatibility matrix](docs/COMPATIBILITY_MATRIX.md)
- [Topology publication admission](docs/TOPOLOGY_PUBLICATION_ADMISSION.md)
- [Full ADR ledger](docs/adr/README.md)
- [Agent skill](skill/SKILL.md)
- [Validation evidence](VALIDATION.md)
