{"id":50391182,"url":"https://github.com/kadubon/certified-memory-governance-layer","last_synced_at":"2026-05-30T18:01:49.379Z","repository":{"id":357716712,"uuid":"1237847700","full_name":"kadubon/certified-memory-governance-layer","owner":"kadubon","description":"Certified Memory Governance Layer for long-running AI agents: strict receipts, append-only ledgers, authority gates, retrieval filtering, telemetry replay, and safe adapters for Mem0, Graphiti, LangMem, and LangGraph.","archived":false,"fork":false,"pushed_at":"2026-05-14T01:46:43.000Z","size":672,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T02:30:31.543Z","etag":null,"topics":["agent-infrastructure","agent-memory","ai-agents","audit-ledger","graphiti","langgraph","langmem","long-running-agents","mem0","memory-governance","memory-management","memory-safety","pydantic","python","retrieval-filtering","typer"],"latest_commit_sha":null,"homepage":"https://kadubon.github.io/github.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kadubon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-13T15:06:58.000Z","updated_at":"2026-05-14T01:46:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kadubon/certified-memory-governance-layer","commit_stats":null,"previous_names":["kadubon/certified-memory-governance-layer"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/kadubon/certified-memory-governance-layer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kadubon%2Fcertified-memory-governance-layer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kadubon%2Fcertified-memory-governance-layer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kadubon%2Fcertified-memory-governance-layer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kadubon%2Fcertified-memory-governance-layer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kadubon","download_url":"https://codeload.github.com/kadubon/certified-memory-governance-layer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kadubon%2Fcertified-memory-governance-layer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33703065,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-infrastructure","agent-memory","ai-agents","audit-ledger","graphiti","langgraph","langmem","long-running-agents","mem0","memory-governance","memory-management","memory-safety","pydantic","python","retrieval-filtering","typer"],"created_at":"2026-05-30T18:01:48.225Z","updated_at":"2026-05-30T18:01:49.370Z","avatar_url":"https://github.com/kadubon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CMGL\n\nCertified Memory Governance Layer for long-running AI agents. Current public API status: `1.1.2`.\n\nCMGL is a local Python governance layer that sits between an agent runtime and a memory backend. It is not a memory database. It decides whether a memory item is procedurally admissible, records evidence in an append-only ledger, and explains every admit/block decision with typed receipts.\n\nThe project is designed for agent systems that already use Mem0, Graphiti, LangMem, LangGraph, or a custom store and need a deterministic control point before memory is written or placed into model context.\n\n## What CMGL Can Do\n\n- Normalize backend-specific memory records into `MemoryEvent`.\n- Guard persistent memory writes, updates, and deletes with structured authority bundles.\n- Block stale, superseded, tombstoned, contradicted, quarantined, contaminated, or unauthorized memory.\n- Keep model inference, regenerated summaries, and synthetic evaluation data out of factual memory by default.\n- Record canonical JSON and `sha256:\u003chex\u003e` digests in an append-only JSONL ledger.\n- Emit receipts for promotion, authority, retrieval filtering, adapter operations, telemetry replay, ledger integrity, compression, and conformance.\n- Run core checks locally without LLM calls, cloud services, hidden telemetry, or API keys.\n\nCMGL proves procedural admissibility under declared policies, evidence, receipts, and ledger verification. It does not prove that a remembered statement is factually true.\n\n## Install And Release Status\n\nCMGL v1.1.2 is available on PyPI.\n\n```bash\nuv add cmgl\n```\n\nFor development from GitHub source:\n\n```bash\nuv add \"cmgl @ git+https://github.com/kadubon/certified-memory-governance-layer.git\"\n```\n\nFor local development from a clone:\n\n```bash\nuv sync --all-extras --dev\nuv run cmgl version\nuv run cmgl doctor --skip-ledger\n```\n\nRelease checklist documents are retained as historical/internal maintenance records. See `docs/release-v1.1.2-checklist.md`.\n\n## 10-Minute Offline Integration\n\nInitialize a local ledger and schemas:\n\n```bash\nuv run cmgl init\n```\n\nCreate structured authority and write memory through the strict path:\n\n```bash\nuv run cmgl authority bundle create \\\n  --action persistent_memory_write \\\n  --actor agent.local \\\n  --scope user:demo \\\n  --source-record \"structured local scope\" \\\n  --out /tmp/cmgl-authority.json\n\nuv run cmgl memory write \\\n  --ledger .cmgl/ledger.jsonl \\\n  --content \"User prefers morning meetings.\" \\\n  --lane user_claim \\\n  --scope user:demo \\\n  --authority-bundle-json /tmp/cmgl-authority.json \\\n  --json\n```\n\nVerify the result:\n\n```bash\nuv run cmgl ledger verify --ledger .cmgl/ledger.jsonl --receipt-json\nuv run cmgl conformance audit --ledger .cmgl/ledger.jsonl --profile strict --json\n```\n\nFor a local demo only, `cmgl memory write --demo-local-authority` creates short-lived synthetic authority evidence. Do not use that flag as production authorization.\n\n## Python API\n\nUse `GovernanceLayer` when you want typed local receipts and a stable integration surface.\n\n```python\nfrom datetime import timedelta\n\nfrom cmgl import (\n    ContaminationLane,\n    GovernanceLayer,\n    ProtectedAction,\n    authorize_bundle,\n    make_declared_scope,\n    make_protected_action_request,\n)\nfrom cmgl.time import now_utc\n\nlayer = GovernanceLayer(ledger=\".cmgl/ledger.jsonl\", profile=\"strict\")\n\nscope = make_declared_scope(\n    actor=\"agent.local\",\n    authority_scope=\"user:demo\",\n    permitted_actions=[ProtectedAction.PERSISTENT_MEMORY_WRITE],\n    expires_at=now_utc() + timedelta(minutes=10),\n)\nrequest = make_protected_action_request(\n    action=ProtectedAction.PERSISTENT_MEMORY_WRITE,\n    actor=\"agent.local\",\n    authority_scope=\"user:demo\",\n    source_record=\"structured local authority scope\",\n    declared_scope=scope,\n)\nauthority = authorize_bundle(request, declared_scope=scope)\n\nbundle = layer.write_memory_bundle(\n    \"User prefers morning meetings.\",\n    lane=ContaminationLane.USER_CLAIM,\n    authority_scope=\"user:demo\",\n    authority_bundle=authority,\n)\n\nassert bundle.decision.value == \"admit\"\nassert layer.verify_ledger().ok\n```\n\n`GovernanceReceiptBundle` is the recommended public result object. It contains the event, candidate, evidence, promotion receipt, ledger append receipts, optional adapter operation receipt, conformance status, and canonical digest.\n\nThe stable public API is documented in `docs/api-stability.md`. Top-level imports from `cmgl` are stable when listed there; deeper modules under `cmgl.contracts.*`, `cmgl.commands.*`, and adapter implementation helpers are more specialized and may evolve with deprecation notes.\n\nFor the formal claim boundary, see `docs/formal-invariants.md` and `docs/proof-obligations.md`. For backend mutation models such as add-only stores, temporal graphs, and tool/store-shaped APIs, see `docs/backend-semantics.md` and `docs/current-view.md`.\n\n## Custom Backend Guard\n\nUse `GuardedMemoryBackend` when you already have persistence callables.\n\n```python\nfrom cmgl import ContaminationLane, GuardedMemoryBackend\n\npersisted = []\n\ndef persist_write(content, *, lane, authority_scope, metadata=None):\n    persisted.append({\"content\": content, \"scope\": authority_scope})\n    return persisted[-1]\n\nguarded = GuardedMemoryBackend(write=persist_write)\n\nresult = guarded.write_memory(\n    \"User prefers morning meetings.\",\n    lane=ContaminationLane.USER_CLAIM,\n    authority_scope=\"user:demo\",\n)\n\nassert result.decision.value == \"block\"\nassert persisted == []\n```\n\n## Adapter Status\n\nAdapters are supported safe integration shims. They work with user-supplied clients, import optional dependencies lazily, and keep external framework setup application-owned.\n\n| Target | Status | What CMGL owns |\n| --- | --- | --- |\n| Mem0 | Supported shim | Guard `add`/`update`/`delete`, bind returned IDs, normalize `search`/`get`/`get_all`, filter retrieval. |\n| Graphiti | Supported async shim | Guard `add_episode`, bind episode/search IDs, normalize `search` and `search_`, filter graph results. |\n| LangMem | Supported shim | Guard manage-memory tool calls, support sync and async tools, bind tool result IDs, filter search-memory output. |\n| LangGraph | Supported helper | Filter retrieved `MemoryEvent` lists and store-shaped items before context construction. |\n| Custom backend | Supported | Use `GovernanceLayer` or `GuardedMemoryBackend`. |\n\nExternal records without explicit status or source evidence are downgraded before policy filtering unless you opt into `trusted_results=True`.\n\nAdapter support means stable shim behavior, fake-client tests, optional dependency isolation, and optional live-smoke support. It does not mean CMGL owns cloud accounts, Neo4j, LLM providers, framework graph topology, or every external SDK version.\n\n## Adapter Examples\n\nMem0:\n\n```python\nfrom cmgl.adapters.mem0 import Mem0Adapter\n\nadapter = Mem0Adapter(mem0_client, authority_scope=\"user:demo\")\n\nbundle = adapter.add(\n    \"User prefers morning meetings.\",\n    authority_bundle=authority,\n)\n\nassert bundle.adapter_operation_receipt is not None\nprint(bundle.adapter_operation_receipt.external_ref.external_id)\n\nfiltered = adapter.filter_search(\"meeting preference\", limit=10)\ncontext_ids = filtered.decision.admitted_memory_ids\n```\n\nGraphiti:\n\n```python\nfrom cmgl.adapters.graphiti import GraphitiAdapter\n\nadapter = GraphitiAdapter(graphiti_client, authority_scope=\"user:demo\")\n\nawait adapter.add_episode(\n    name=\"preference-update\",\n    episode_body=\"User now prefers afternoon meetings.\",\n    source_description=\"user correction in session 42\",\n    authority_bundle=authority,\n)\n\nfiltered = await adapter.filter_search(\"meeting preference\")\n```\n\nLangMem:\n\n```python\nfrom cmgl.adapters.langmem import LangMemAdapter\n\nadapter = LangMemAdapter(authority_scope=\"user:demo\")\n\nadapter.manage_memory(\n    \"create\",\n    content=\"User prefers concise summaries.\",\n    manage_tool=manage_memory_tool,\n    authority_bundle=authority,\n)\nfiltered = adapter.filter_search(\"summary preference\", search_tool=search_memory_tool)\n```\n\nLangGraph:\n\n```python\nfrom cmgl.adapters.langgraph import LangGraphAdapter\n\nadapter = LangGraphAdapter(authority_scope=\"user:demo\")\ncmgl_node = adapter.as_node(\n    query_key=\"query\",\n    memory_key=\"retrieved_memories\",\n    output_key=\"admitted_memories\",\n)\n\nstate = cmgl_node(state)\ncontext = [event.content for event in state[\"admitted_memories\"]]\n```\n\n## Live Adapter Setup\n\nOffline tests use fake clients. Release/main live smoke is separate and should run only in a protected GitHub Environment.\n\n```bash\nuv run cmgl adapters doctor\nuv run cmgl adapters live-smoke --target all --dry-run\nuv run python scripts/live_adapter_smoke.py --target all\n```\n\nLive smoke requirements:\n\n- Mem0: `cmgl[mem0]`, provider environment required by Mem0, and an isolated `MEM0_TEST_USER_PREFIX`.\n- Graphiti: `cmgl[graphiti]`, Neo4j connection (`NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD`), and provider environment required by Graphiti.\n- LangMem: `cmgl[langmem]` and local LangGraph `InMemoryStore` for smoke.\n- LangGraph: `cmgl[langgraph]` and local store/state helpers.\n\nWhen provider secrets are absent, `scripts/live_adapter_smoke.py --target all` skips provider-backed Mem0/Graphiti calls and still runs local LangMem/LangGraph smoke. Add `--require-live-env` when a protected release gate must fail on missing provider configuration.\n\nSee `docs/adapters.md` and `docs/live-ci.md` for full live setup.\n\n## Operational Commands\n\n```bash\nuv run cmgl validate canonical\nuv run cmgl schema export /tmp/cmgl-schemas\nuv run cmgl validate ledger examples/conformance/strict_ledger.valid.jsonl\nuv run cmgl telemetry replay examples/conformance/telemetry_replay.valid.jsonl --profile strict --json\nuv run python examples/governance_layer_demo.py\nuv run python examples/strict_authority_demo.py\nuv run python examples/ledger_receipt_demo.py\n```\n\nUseful commands:\n\n- `cmgl init [path]`\n- `cmgl memory write`\n- `cmgl retrieve filter`\n- `cmgl ledger verify`\n- `cmgl validate record|ledger|canonical`\n- `cmgl telemetry ingest|replay`\n- `cmgl conformance audit|explain`\n- `cmgl doctor --skip-ledger`\n- `cmgl adapters doctor`\n- `cmgl adapters live-smoke`\n\n## Production Readiness Checklist\n\n- Use strict `GovernanceLayer` defaults.\n- Store authority as `AuthorityBundle` or `AuthorityEvidenceBundle`, not free text.\n- Keep provider keys in environment variables or secret managers, never in ledgers, docs, fixtures, or issue reports.\n- Run `cmgl ledger verify` and `cmgl conformance audit` in CI or deployment checks.\n- Treat failed adapter operation receipts as incidents for the external memory backend.\n- Quarantine broken ledgers before reusing them in agent context construction.\n- Keep live adapter CI on protected release/main branches, not fork PRs.\n- Review optional dependency licenses and external service terms before commercial deployment.\n\n## Security Model\n\nCMGL is local-first and deterministic. Core tests and examples do not use network services, paid APIs, LLM providers, private datasets, cookies, tokens, or hidden telemetry.\n\nControls include:\n\n- Canonical JSON and SHA-256 digests.\n- Append-only JSONL ledger with prefix verification.\n- Structured authority bundles for protected actions.\n- Natural-language-only authorization rejection.\n- Fail-closed receipt and semantic-rule validation.\n- Adapter operation receipts that record whether the external store was not called, succeeded, failed, or was compensated.\n- Optional signing extra isolated from the core install.\n- PyPI Trusted Publishing / OIDC in the publish workflow.\n\n## Failure Modes\n\n- Missing authority: protected writes block and external adapters are not called.\n- External persistence failure: CMGL records a failed adapter operation receipt and a quarantine record.\n- Unbound external update/delete: adapters block by default unless you explicitly allow migration mode.\n- Broken ledger prefix: verification fails; do not use the ledger for context construction until investigated.\n- Expired authority scope: strict protected actions block.\n- Framework API drift: optional adapters isolate external API changes; core CMGL remains local and deterministic.\n\n## Limits\n\nCMGL does not provide:\n\n- Factual-truth guarantees.\n- A memory database, vector store, hosted service, dashboard, or LLM provider wrapper.\n- Legal, compliance, or safety certification.\n- Autonomous external actions.\n- Deep ownership of Mem0, Graphiti, LangMem, LangGraph, Letta, Cognee, or MemOS deployment.\n- A full implementation of the author's prior research repositories.\n\nCMGL implements a bounded executable subset: OAWM-style admissibility, MemoryFlow-style telemetry replay, OASG-style ledgers, no-meta-authority protected-action gates, CWC-style lower-bound reporting, semantic compression certificates, and SEC-style contamination lanes. See `docs/reference-mapping.md`.\n\n## CI Recipe\n\n```bash\nuv lock\nuv sync --locked --all-extras --dev\nuv run ruff check .\nuv run ruff format --check .\nuv run mypy src\nuv run pytest --cov=cmgl\nuv run cmgl doctor --skip-ledger\nuv run cmgl adapters doctor\nuv run cmgl adapters live-smoke --target all --dry-run\nuv run cmgl validate canonical\nuv run python -m build\nuv run python scripts/check_publishability.py\nuv run pip-audit\n```\n\nRelease preparation also requires:\n\n```bash\nuv build\nuv run python scripts/check_publishability.py\n```\n\n## License\n\nApache-2.0. Optional adapter targets are not vendored; review optional dependency licenses and service terms before deploying them.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkadubon%2Fcertified-memory-governance-layer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkadubon%2Fcertified-memory-governance-layer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkadubon%2Fcertified-memory-governance-layer/lists"}