Metadata-Version: 2.4
Name: causal-memory-layer
Version: 0.4.0
Summary: Causal Memory Layer — SDK for recording, auditing, and analyzing causal chains in systems
Author-email: CML Project <dev@causal-memory.dev>
License: MIT License
        
        Copyright (c) 2025 Aleksey Safonov
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/safal207/Causal-Memory-Layer
Project-URL: Repository, https://github.com/safal207/Causal-Memory-Layer
Project-URL: Issues, https://github.com/safal207/Causal-Memory-Layer/issues
Project-URL: Changelog, https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md
Keywords: causal,audit,provenance,security,compliance,ebpf,tracing,causal-memory,ai-governance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE_COMMERCIAL.md
Requires-Dist: pyyaml>=6.0
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == "api"
Requires-Dist: httpx>=0.27; extra == "api"
Requires-Dist: uvicorn[standard]>=0.29; extra == "api"
Requires-Dist: python-multipart>=0.0.9; extra == "api"
Requires-Dist: slowapi>=0.1.9; extra == "api"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: fastapi>=0.110; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: uvicorn[standard]>=0.29; extra == "dev"
Requires-Dist: python-multipart>=0.0.9; extra == "dev"
Requires-Dist: slowapi>=0.1.9; extra == "dev"
Dynamic: license-file

# Causal Memory Layer (CML)

[![CI](https://github.com/safal207/Causal-Memory-Layer/actions/workflows/ci.yml/badge.svg)](https://github.com/safal207/Causal-Memory-Layer/actions/workflows/ci.yml)
[![Package Validation](https://github.com/safal207/Causal-Memory-Layer/actions/workflows/python-package-validation.yml/badge.svg)](https://github.com/safal207/Causal-Memory-Layer/actions/workflows/python-package-validation.yml)
![Status](https://img.shields.io/badge/status-active-brightgreen)
![Audit](https://img.shields.io/badge/audit-causal%20lineage-blue)
![License](https://img.shields.io/badge/license-MIT-orange)
[![Safety Eval](https://img.shields.io/badge/safety--eval-6%2F6%20matched-purple)](docs/evidence/BENCHMARK_EVIDENCE_SNAPSHOT.md)

![CML before-after causal audit visual](docs/assets/cml-before-after.svg)

## Why CML?

**Logs show what happened. CML checks why it was allowed.**

A workflow can pass every functional test and still be causally invalid: the action succeeded, but the approval, intent, or responsibility lineage is missing, ambiguous, or broken.

```text
ordinary log:  action completed -> OK
CML audit:     parent_cause=approval-42 -> MISSING_PARENT
```

CML is an open-source causal audit layer for structured action traces, AI-agent workflows, high-trust automation, and reviewable safety infrastructure.

> A system may be functionally correct while being causally invalid.

**Star this repo if you care about auditable AI agents, deterministic oversight, causal traces, and open-source AI safety infrastructure.**

## 30-second demo

Run the local API:

```bash
docker compose up --build
```

Then follow the Docker walkthrough:

```text
docs/demo/DOCKER_CAUSAL_MEMORY_WALKTHROUGH.md
```

Expected example finding:

```text
CML-AUDIT-R1-MISSING_PARENT
```

The action may look operationally valid, but CML asks whether its causal parent exists.

## Use CML when you need to audit

- AI-agent tool calls and action chains.
- Human approval handoffs.
- Automation workflows with high-trust actions.
- Fintech or review-heavy decision paths.
- Structured traces where responsibility lineage matters.
- Research benchmarks for causal validity in agentic systems.

## Agent-audit MCP integration

CML can also run as an experimental MCP tool server for AI-agent audit workflows.

```bash
pip install -e ".[mcp]"
cml-mcp
```

See [`docs/integrations/MCP_AGENT_AUDIT.md`](docs/integrations/MCP_AGENT_AUDIT.md) for local MCP client setup and available tools.

For a short coding-assistant setup path, see [`docs/integrations/CURSOR_MCP_QUICKSTART.md`](docs/integrations/CURSOR_MCP_QUICKSTART.md).

## How CML differs

| System type | Usually answers | CML adds |
| :--- | :--- | :--- |
| Logs | What happened? | Was the action causally permitted? |
| Tracing | Where did execution go? | Did responsibility lineage survive the workflow? |
| Observability | What failed operationally? | What succeeded but had broken causal lineage? |
| Policy checks | Is this allowed now? | Why was this specific action allowed in this trace? |
| CML | Why was this action allowed? | Narrow audit primitive, not a full runtime safety stack. |

## Fast validation

```bash
pip install -e ".[dev]"
pytest
python scripts/run_safety_eval.py
```

Dashboard:

```text
https://safal207.github.io/Causal-Memory-Layer/
```

## Review links

- Start here: [`docs/START_HERE.md`](docs/START_HERE.md)
- Reviewer path: [`docs/REVIEWER_PATH.md`](docs/REVIEWER_PATH.md)
- Research map: [`docs/research/CML_RESEARCH_MAP.md`](docs/research/CML_RESEARCH_MAP.md)
- Non-claims: [`docs/NON_CLAIMS.md`](docs/NON_CLAIMS.md)
- Portfolio relationship: [`docs/PORTFOLIO_RELATIONSHIP.md`](docs/PORTFOLIO_RELATIONSHIP.md)
- Benchmark evidence: [`docs/evidence/BENCHMARK_EVIDENCE_SNAPSHOT.md`](docs/evidence/BENCHMARK_EVIDENCE_SNAPSHOT.md)
- External validation protocol: [`docs/evidence/EXTERNAL_VALIDATION_PROTOCOL.md`](docs/evidence/EXTERNAL_VALIDATION_PROTOCOL.md)
- Technical report outline: [`docs/research/TECHNICAL_REPORT_OUTLINE.md`](docs/research/TECHNICAL_REPORT_OUTLINE.md)
- Funding / research evidence: [`docs/GRANT_EVIDENCE.md`](docs/GRANT_EVIDENCE.md)
- Docker walkthrough: [`docs/demo/DOCKER_CAUSAL_MEMORY_WALKTHROUGH.md`](docs/demo/DOCKER_CAUSAL_MEMORY_WALKTHROUGH.md)
- MCP agent-audit integration: [`docs/integrations/MCP_AGENT_AUDIT.md`](docs/integrations/MCP_AGENT_AUDIT.md)
- Cursor MCP quickstart: [`docs/integrations/CURSOR_MCP_QUICKSTART.md`](docs/integrations/CURSOR_MCP_QUICKSTART.md)
- Cause Band concept: [`docs/research/CAUSE_BAND.md`](docs/research/CAUSE_BAND.md)
- Cause Band trajectory walkthrough: [`docs/demo/CAUSE_BAND_TRAJECTORY_WALKTHROUGH.md`](docs/demo/CAUSE_BAND_TRAJECTORY_WALKTHROUGH.md)
- Agent intent drift example: [`docs/demo/AGENT_INTENT_DRIFT_CAUSE_BAND_EXAMPLE.md`](docs/demo/AGENT_INTENT_DRIFT_CAUSE_BAND_EXAMPLE.md)
- Dormant Causal Patterns: [`docs/research/DORMANT_CAUSAL_PATTERNS.md`](docs/research/DORMANT_CAUSAL_PATTERNS.md)
- Temporal Causal Watchpoints: [`docs/research/TEMPORAL_CAUSAL_WATCHPOINTS.md`](docs/research/TEMPORAL_CAUSAL_WATCHPOINTS.md)
- Experimental Cause Band audit flag: [`docs/experimental/CAUSE_BAND_AUDIT_FLAG.md`](docs/experimental/CAUSE_BAND_AUDIT_FLAG.md)
- Quantum causal audit future direction: [`docs/research/QUANTUM_CAUSAL_AUDIT_FUTURE_DIRECTION.md`](docs/research/QUANTUM_CAUSAL_AUDIT_FUTURE_DIRECTION.md)
- Causal invalidity patterns: [`docs/research/CAUSAL_INVALIDITY_PATTERNS.md`](docs/research/CAUSAL_INVALIDITY_PATTERNS.md)
- Audit findings glossary: [`docs/audit/FINDINGS_GLOSSARY.md`](docs/audit/FINDINGS_GLOSSARY.md)
- LTP / CML bridge: [`docs/LTP_CML_BRIDGE.md`](docs/LTP_CML_BRIDGE.md)
- Roadmap: [`ROADMAP.md`](ROADMAP.md)
- Security: [`SECURITY.md`](SECURITY.md)
- License: [`LICENSE`](LICENSE)

## Current artifact

This repository already contains a working technical artifact, not only a concept.

Current components include:

- Python causal validation and audit engine;
- causal chain reconstruction utilities;
- CLI commands for lineage validation and chain inspection;
- API layer and store interface;
- example logs and audit outputs;
- tests for chain logic, audit rules, and CTAG behavior;
- API smoke tests for health, audit, and CTAG decode;
- deterministic safety-eval benchmark with fixtures and tracked results;
- documentation for vCML semantics and audit rules.

Key implementation entry points:

- `cml/audit.py`
- `cml/chain.py`
- `cli/main.py`
- `api/server.py`
- `tests/test_audit.py`
- `tests/test_api_smoke.py`

## Problem

Many systems record events, outputs, traces, and metrics, but do not validate the causal structure behind authorization and action.

That creates blind spots such as:

- actions that appear valid but have no grounded parent cause;
- ambiguous or malformed root authority;
- actions that succeed operationally while losing approval lineage;
- state transitions that cannot be tied back to intent, permission, and responsibility.

For agentic systems, this matters because output review alone can miss causally invalid action chains.

## What CML does

CML checks whether a high-trust action or state transition was causally valid, not only whether it occurred.

It focuses on:

- validating causal links between actions and prior authorization;
- preserving responsibility lineage across multi-step workflows;
- checking intent and permission continuity across transitions;
- detecting suspicious or invalid lineage such as missing parents, malformed roots, or broken handoffs;
- validating causal coherence from structured logs and traces.

## Evidence snapshot

- Deterministic benchmark fixtures with expected audit findings: `benchmarks/fixtures/`
- Current tracked benchmark result: `6/6 matched`
- Benchmark runner: `python scripts/run_safety_eval.py`
- Tracked report: `benchmarks/RESULTS.md`
- Reviewer-friendly benchmark interpretation: `docs/evidence/BENCHMARK_EVIDENCE_SNAPSHOT.md`
- Larger-grant expansion path: `docs/evidence/BENCHMARK_EXPANSION_PLAN_50K_100K.md`
- External validation protocol: `docs/evidence/EXTERNAL_VALIDATION_PROTOCOL.md`

## External reproducibility evidence

External validation notes will be listed here as they are contributed.

Current external validation tasks:

- Full local validation path: [`#77`](https://github.com/safal207/Causal-Memory-Layer/issues/77)
- MCP demo runner validation: [`#123`](https://github.com/safal207/Causal-Memory-Layer/issues/123)

Validation note template:

```text
docs/evidence/external_validation/TEMPLATE_MCP_DEMO_RUNNER.md
```

This section is intentionally evidence-first: it should only list external notes after they are contributed. It does not claim production safety, compliance readiness, enforcement behavior, or stable Cause Band semantics.

## Repository map

- `cml/`: core Python implementation
- `cli/`: command-line tooling
- `api/`: API and store layer
- `vcml/`: vCML semantics, format, audit, and boundary docs
- `examples/`: sample logs and reports
- `benchmarks/`: deterministic benchmark fixtures and results
- `tests/`: regression coverage
- `docs/`: supporting docs for review, research, and deployment

## Scope

CML does not claim to solve all AI safety, security, or compliance problems.

It contributes one focused primitive:

```text
causal-validity checking for structured action traces
```

See [`docs/NON_CLAIMS.md`](docs/NON_CLAIMS.md) for the full scope boundary.

## Research direction

The strongest research direction for CML is causal validity checking for agentic oversight.

A useful framing is:

> How can we detect actions that appear valid at the surface level but are causally invalid because authorization, approval, or responsibility lineage is missing, ambiguous, or broken?

## Bottom line

A system may be functionally correct while being causally invalid.

CML exists to make that distinction inspectable.
