# https://github.com/safal207/Causal-Memory-Layer Project Manual

Generated at: 2026-06-18 11:59:43 UTC

## Table of Contents

- [Introduction to CML](#page-1)
- [Causal Records, Chains, CTAG and Audit Rules](#page-2)
- [CLI, REST API, MCP Server and Deployment](#page-3)
- [vCML Reference Implementation, LLM Integrations and Research Directions](#page-4)

<a id='page-1'></a>

## Introduction to CML

### Related Pages

Related topics: [Causal Records, Chains, CTAG and Audit Rules](#page-2), [CLI, REST API, MCP Server and Deployment](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md)
- [cml/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py)
- [cml/record.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/record.py)
- [cml/report.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/report.py)
- [cli/main.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cli/main.py)
- [vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md)
- [vcml/hardware/CTAG-8-16.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/hardware/CTAG-8-16.md)
- [ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md)
- [PRICING.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/PRICING.md)
- [integrations/vscode-cml/package.json](https://github.com/safal207/Causal-Memory-Layer/blob/main/integrations/vscode-cml/package.json)
- [integrations/vscode-cml/src/extension.ts](https://github.com/safal207/Causal-Memory-Layer/blob/main/integrations/vscode-cml/src/extension.ts)
- [examples/crewai_signed_receipt_sidecar.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/crewai_signed_receipt_sidecar.py)
- [scripts/run_safety_eval.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/scripts/run_safety_eval.py)
- [CONTRIBUTING.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/CONTRIBUTING.md)
</details>

# Introduction to CML

## What is CML?

The **Causal Memory Layer (CML)** is an open-source causal audit layer for structured action traces. It focuses on a single, focused primitive: validating whether an action has a valid causal permission, responsibility, and upstream lineage — not merely a recorded event. Source: [README.md:1-15]()

Many systems record events, outputs, traces, and metrics, but they do not validate the *causal structure* behind authorization and action. CML exists to make that distinction inspectable. As stated in the project positioning:

> A system may be functionally correct while being causally invalid. CML exists to make that distinction inspectable.

Source: [README.md:96-99]()

The repository is not just a concept; it ships a working technical artifact including a Python SDK, CLI, REST API, examples for seven LLM ecosystems, regression tests, and a deterministic safety-eval benchmark. Source: [README.md:24-39]()

## Core Architecture and Data Model

CML is organized around a minimal semantic unit called a **CausalRecord**, defined in the vCML FORMAT v0 draft. Source: [vcml/FORMAT.md:6-15]()

A CausalRecord captures **permission and responsibility**, not outcomes, and is required to express six core fields:

| Field | Purpose |
|---|---|
| `id` | Unique identifier (monotonic or UUID-based) |
| `timestamp` | Time when the boundary was crossed |
| `actor` | Entity that initiated the action (pid, uid, gid, comm) |
| `action` | Boundary type (`exec`, `open`, `read`, `write`, `connect`, `send`) |
| `object` | Target of the action (path hash, network address, fd, etc.) |
| `permitted_by` | Reference to permission, capability, policy, or prior cause |
| `parent_cause` | Identifier of the causal record that enabled this action |

Source: [vcml/FORMAT.md:24-65](), [cml/record.py:1-65]()

The Python SDK exposes a clean public API surface. Importing the package gives access to the record model, CTAG computation, chain reconstruction, the audit engine, and report generation. Source: [cml/__init__.py:1-35]()

```mermaid
flowchart LR
    A[Causal Trace<br/>JSONL] --> B[load_jsonl]
    B --> C[AuditEngine<br/>R1–R4]
    C --> D[AuditResult]
    D --> E[to_markdown / to_json / to_text]
    C --> F[reconstruct_chain]
    F --> G[CTAG compute/decode]
    H[CLI: cml audit / chain / report] --> C
    I[FastAPI: POST /audit] --> C
```

Source: [cml/__init__.py:18-35](), [cli/main.py:1-25](), [cml/report.py:1-30]()

## Audit Rules, CTAG, and Chain Reconstruction

CML ships four core audit rules (**R1–R4**) referenced throughout the codebase and pricing documentation. Source: [PRICING.md:18-19](), [README.md:25-30]() The AuditEngine takes a list of `CausalRecord` objects and returns an `AuditResult` with findings, severity, and aggregate counts. Source: [cml/__init__.py:30-31]()

The **CTAG** (Causal Tag) is a 16-bit packed encoding carrying DOM, CLASS, GEN, LHINT, and SEAL fields. It is computed deterministically and is also mappable to hardware metadata (CTAG-8 compact form) for cache-line and pointer use cases. Source: [vcml/hardware/CTAG-8-16.md:6-32](), [cml/__init__.py:25-28]()

Chain reconstruction (`reconstruct_chain`) walks the `parent_cause` graph backwards so a user can answer "what allowed this action?" — a question central to approval-lineage detection, demonstrated in v0.4.1. Source: [README.md:32-33](), [cml/__init__.py:29]()

Reports can be emitted in three formats:

- `to_json(result)` — machine-readable JSON
- `to_markdown(result, title=...)` — human-readable with severity emoji per finding
- `to_text(result)` — plain-text summary

Source: [cml/report.py:19-85]()

## Surface Area: CLI, API, IDE, and Integrations

The CLI entry point validates each JSONL line strictly (type-checks `id`, `timestamp`, `action`, `permitted_by`) and surfaces meaningful errors with line numbers. Source: [cli/main.py:15-50]()

The FastAPI server exposes endpoints including `GET /health` and `POST /audit` (CTAG decode is also a target of community smoke tests). Source: [README.md:35-39]() This is reinforced by community issue #47, which proposed adding smoke tests for health, audit, and CTAG decode to make the local API safer to change. Source: community context — issue #47

A **VS Code extension** (`vscode-cml`) registers three commands — `cml.auditCurrentLog`, `cml.showChainForSelectedRecord`, and `cml.auditExampleLog` — and delegates all heavy work to the Python CLI, keeping the IDE integration thin. Source: [integrations/vscode-cml/package.json:7-40](), [integrations/vscode-cml/src/extension.ts:1-35]()

Beyond the core SDK, the project ships deterministic mappings for seven LLM ecosystems (OpenAI, Claude, Gemini, Grok/xAI, Qwen, Kimi, DeepSeek), a CrewAI-style agent trace audit example, and an approval-lineage demo. Source: [README.md:25-37](), [examples/crewai_signed_receipt_sidecar.py:1-20]()

A safety-eval benchmark is also available via `scripts/run_safety_eval.py`, which renders text and optional Markdown reports from fixtures under `benchmarks/fixtures/`. Source: [scripts/run_safety_eval.py:1-30]()

## Release History, Scope, and Boundaries

The project has progressed from a conceptual foundation (v0.1.0 — *Foundation*, scope and invariants only) through a PyPI-ready prototype (v0.4.0), an **Approval Lineage Demo** (v0.4.1), and into v0.5.1 (*Audit Semantics*) which introduced read-only causal gap detection and SECRET → NET_OUT validation with no enforcement. Source: community context — releases v0.1.0-foundation, v0.4.0, v0.4.1, v0.5.1-audit-semantics

Active research directions include **signed causal receipts with temporal provenance**, which add proof of authorship on top of CML's causal validity checks. A research-only demo (`crewai_signed_receipt_sidecar.py`) explicitly documents its non-claims: it is not production cryptographic signing, not wallet identity, and not third-party safety certification. Source: [examples/crewai_signed_receipt_sidecar.py:1-20](), community context — issue #139

CML is delivered under an **Open Core** model: the Core SDK is MIT-licensed and free forever, while hosted Pro/Enterprise tiers are planned but not yet available. Self-hosted use of `api/server.py` remains free today. Source: [PRICING.md:1-22]()

The `cml.experimental` package is explicitly **non-normative** — APIs there may change while research concepts mature into stable CML semantics. Source: [cml/experimental/__init__.py:1-5]()

Contributions are welcomed via small, focused pull requests with tests and documentation updates; see the project's contribution checklist for formatting, linting, and secret hygiene. Source: [CONTRIBUTING.md:1-18]()

## See Also

- [Causal Record Format (vCML)](FORMAT.md)
- [Audit Engine and Rules R1–R4](audit-engine.md)
- [CTAG Encoding and Hardware Mapping](ctag.md)
- [CLI and API Reference](cli-api.md)
- [LLM Provider Interoperability Matrix](llm-provider-matrix.md)

---

<a id='page-2'></a>

## Causal Records, Chains, CTAG and Audit Rules

### Related Pages

Related topics: [Introduction to CML](#page-1), [CLI, REST API, MCP Server and Deployment](#page-3), [vCML Reference Implementation, LLM Integrations and Research Directions](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [cml/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py)
- [cml/record.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/record.py)
- [cml/chain.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/chain.py)
- [cml/ctag.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/ctag.py)
- [cml/audit.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/audit.py)
- [cml/report.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/report.py)
- [cli/chain.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cli/chain.py)
- [vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md)
- [examples/grok_xai_causal_audit.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/grok_xai_causal_audit.py)
- [cml/experimental/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/experimental/__init__.py)
</details>

# Causal Records, Chains, CTAG and Audit Rules

The Causal Memory Layer (CML) is a read-only audit primitive that checks whether structured action traces have a valid causal structure: a coherent `parent_cause` lineage, an explicit `permitted_by` reference, and (optionally) signed receipts. The core data unit is the `CausalRecord`, the core navigation primitive is the reconstructed chain, the core compaction primitive is the 16-bit CTAG, and the core reasoning primitive is the `AuditEngine` with rules R1–R4 plus custom rules. Together these four building blocks let a reviewer answer the question: "Did this action have a valid upstream cause?"

## Causal Records (vCML Format v0)

The minimum semantic unit of causal memory is `CausalRecord`, defined in [cml/record.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/record.py) and specified by [vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md). A record captures a single boundary-crossing event and is *append-only and immutable* — meaning is preserved, not outcomes. Required fields include:

- `id` — monotonic or UUID-based identifier of the record.
- `timestamp` — when the boundary was crossed (nanosecond precision).
- `actor` — entity that initiated the action (pid, uid, gid, comm, optional ppid).
- `action` — canonical boundary type from the `Action` constants (`exec`, `open`, `read`, `write`, `connect`, `send`).
- `object` — the target (path hash, network address+port, fd id, etc.).
- `permitted_by` — semantic reference to a policy, capability, or prior cause.
- `parent_cause` — id of the causal record that enabled this action, or `null` for explicit roots.

The format notes that if `parent_cause` is `null` due to a causal gap (not a root event), `permitted_by` SHOULD be `"unobserved_parent"`. Records can be loaded from JSONL with `load_jsonl` exported in [cml/__init__.py:12-25](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py).

## Chain Reconstruction

Chain reconstruction walks `parent_cause` links from any record back to its root. The library implementation in [cml/chain.py:13-44](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/chain.py) exposes `reconstruct_chain(record_id, index)`, which returns a root-first list, with cycle and `max_depth` guards to prevent infinite loops on corrupt logs. `find_root` and `has_path` complete the path-query surface.

The CLI implementation in [cli/chain.py:10-50](https://github.com/safal207/Causal-Memory-Layer/blob/main/cli/chain.py) returns a richer dictionary that explicitly flags `has_gap` and `gap_note`, and an `r3_context` block for SECRET access that shares a PID with the target but is not in the chain. This is the basis for the v0.5.1 *Audit Semantics* release's "causal gap detection" feature.

## CTAG — Causal Tagging

CTAG is a compact 16-bit tag computed from the causal semantics of a record, designed to make permission and class fingerprints searchable without storing the full record. The computation is exposed via `compute_ctag`, `decode_ctag`, and `compute_lhint` in [cml/__init__.py:23-26](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py), with `DOM` and `CLASS` enums and a `CTAGState` container grouping `DOM`, `CLASS`, `GEN`, `LHINT`, and `SEAL` fields. A practical usage is shown in [examples/grok_xai_causal_audit.py:35-50](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/grok_xai_causal_audit.py), where `compute_ctag(CLASS=..., DOM=...)` is called on agent tool-use records.

## Audit Engine and Rules

The `AuditEngine` (configured via `AuditConfig`, returning `AuditResult` with `Finding` objects tagged by `Severity`) lives in [cml/audit.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/audit.py) and is re-exported by [cml/__init__.py:27-28](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py). The engine applies:

- **R1 — MISSING_PARENT**: detects records whose `parent_cause` is set but absent from the log.
- **R2 / R3 — SECRET → NET_OUT validation**: a secret access that is not causally linked to a same-PID egress record produces a `r3_context` finding.
- **R4 — chain integrity**: a root-first traversal checks for gaps, cycles, and broken lineage.
- **Custom rules** (e.g. `R8_DATA_EGRESS_REQUIRES_HUMAN_APPROVAL`) can declare a `trigger_class`, a `require_ancestor_class`, and a `require_ancestor_permitted_by_prefix` — see the YAML inline in [examples/grok_xai_causal_audit.py:31-49](https://github.com/safal207/Causal-Memory-Layer/blob/main/examples/grok_xai_causal_audit.py).

```mermaid
flowchart LR
    A[JSONL log] --> B[load_jsonl]
    B --> C[CausalRecord index]
    C --> D[AuditEngine.run]
    C --> E[reconstruct_chain]
    D --> F[AuditResult + Findings]
    E --> G[chain report]
    F --> H[to_markdown / to_json / to_text]
    G --> H
```

The renderer in [cml/report.py:30-60](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/report.py) produces Markdown, JSON, and text reports with severity emojis, totals, and a "passed()" verdict. Experimental research helpers (e.g. Cause Band drift) are isolated under [cml/experimental/](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/experimental/__init__.py) and are explicitly *non-normative*.

## Community-Driven Extensions

The community is actively extending these primitives. The [v0.5.1 Audit Semantics release](https://github.com/safal207/Causal-Memory-Layer/releases/tag/v0.5.1-audit-semantics) introduced causal gap detection and SECRET → NET_OUT validation as a read-only meaning layer. Issue [#139](https://github.com/safal207/Causal-Memory-Layer/issues/139) proposes *signed causal receipts with temporal provenance* — a sidecar pattern already demonstrated in `examples/crewai_signed_receipt_sidecar.py` — to add proof of authorship on top of CML's causal validity checks. Issue [#141](https://github.com/safal207/Causal-Memory-Layer/issues/141) shows that adding any such research note must not accidentally embed secrets in committed fixtures. Issues [#65](https://github.com/safal207/Causal-Memory-Layer/issues/65) and [#66](https://github.com/safal207/Causal-Memory-Layer/issues/66) request a plain-language glossary of audit finding codes (e.g. `CML-AUDIT-R1-MISSING_PARENT`, `CML-AUDIT-HIGH_RISK_WITHOUT_APPROVAL`) to make these rules approachable for new users.

## See Also

- [Causal Memory Layer — README](README.md)
- [vCML Causal Record Format (Draft v0)](vcml/FORMAT.md)
- [Audit Findings Glossary](docs/audit/FINDINGS_GLOSSARY.md)
- [Reviewer Path](docs/REVIEWER_PATH.md)
- [Non-Claims / Scope Boundary](docs/NON_CLAIMS.md)

---

<a id='page-3'></a>

## CLI, REST API, MCP Server and Deployment

### Related Pages

Related topics: [Introduction to CML](#page-1), [Causal Records, Chains, CTAG and Audit Rules](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [cli/main.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cli/main.py)
- [cli/audit.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cli/audit.py)
- [cli/chain.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cli/chain.py)
- [api/server.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/api/server.py)
- [api/store.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/api/store.py)
- [cml/integrations/mcp/server.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/integrations/mcp/server.py)
- [cml/integrations/mcp/core.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/integrations/mcp/core.py)
- [scripts/run_mcp_demo_payloads.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/scripts/run_mcp_demo_payloads.py)
- [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md)
- [ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md)
- [demos/secret_to_network_causal_invalid/README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/demos/secret_to_network_causal_invalid/README.md)
- [READY_FOR_REVIEW.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/READY_FOR_REVIEW.md)
- [cml/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py)
- [vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md)
</details>

# CLI, REST API, MCP Server and Deployment

Causal Memory Layer (CML) ships three user-facing entry points and a deployable surface: a command-line tool, a FastAPI-based REST server, an MCP (Model Context Protocol) server, and containerized deployment artifacts. Together they expose the same causal-validation and audit primitives that live in the `cml` package to scripts, HTTP clients, AI agent runtimes, and hosted services. Source: [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md) lists `cli/main.py`, `api/server.py`, and the MCP integration as key implementation entry points.

## Command-Line Interface

The CLI is the canonical local interface. It is implemented as a small `argparse` program in `cli/main.py` and exposes two primary subcommands: `audit` and `chain`. Source: [cli/main.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cli/main.py).

```text
python -m cli.main audit <file.jsonl> [--format json|text]
python -m cli.main chain <file.jsonl> <record_id>
```

Before any audit logic runs, the CLI performs strict validation of each input record. The required keys are `id`, `timestamp`, `actor`, `action`, `object`, and `permitted_by`; `id`, `action`, and `permitted_by` must be non-empty strings, and `timestamp` must be a strict integer (booleans are rejected). Source: [cli/main.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cli/main.py) (`_is_strict_int`, `_validate_raw_record`). Validation errors carry the source line number, which keeps failures localized to a specific JSONL line.

The `audit` subcommand runs the CML `AuditEngine` and emits either human-readable text or a structured JSON `AuditResult`. The `chain` subcommand reconstructs the lineage for a given record id, allowing operators to inspect upstream authorization even when surface output looks correct. The same invocation pattern is used in the SECRET→NET_OUT demo, which detects a missing causal chain for a network send: Source: [demos/secret_to_network_causal_invalid/README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/demos/secret_to_network_causal_invalid/README.md) shows `python -m cli.main chain examples/secret_to_net_log.jsonl b3` exposing the failure under rule `CML-AUDIT-R3-SECRET_NET_MISSING_CHAIN`.

## REST API

The REST surface is a FastAPI application in `api/server.py`, backed by a pluggable store interface in `api/store.py`. Source: [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md) names `api/server.py` as a key entry point. The server exposes the endpoints required by the smoke-test contract:

| Endpoint | Purpose | Notes |
|---|---|---|
| `GET /health` | Reports status and version | Used by uptime checks and CI smoke tests |
| `POST /audit` | Accepts a minimal JSON audit request | Returns an `AuditResult`-shaped JSON document |
| CTAG decode endpoint | Decodes a CTAG token | Surfaces `DOM`, `CLASS`, and state from `cml.ctag` |

The API smoke tests cover these three surfaces and were motivated by community request #47, which called for a small test suite to make the local API "safer to change and easier to trust." Source: community issue [#47](https://github.com/safal207/Causal-Memory-Layer/issues/47). The API reuses the same `AuditEngine`, `CausalRecord`, and CTAG primitives exposed through the package boundary in `cml/__init__.py` (`AuditEngine`, `AuditResult`, `decode_ctag`, `reconstruct_chain`).

## MCP Server

CML also ships a Model Context Protocol integration that lets AI agent runtimes invoke causal checks as tools. The MCP core logic lives in `cml.integrations.mcp.core`, and the transport-facing server is `cml/integrations/mcp/server.py`. Source: [scripts/run_mcp_demo_payloads.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/scripts/run_mcp_demo_payloads.py) imports `cml.integrations.mcp.core` and calls three tool functions: `health()`, `audit_trace(payload)`, and `evaluate_cause_band(payload)`. The script drives the server with fixture payloads located in `examples/mcp/` (e.g., `audit_trace_missing_parent.json` and `evaluate_cause_band_degrading.json`), demonstrating that an MCP client can ask CML to validate a trace or evaluate a cause band without linking the CML Python module directly.

The MCP integration is part of the broader "MCP agent-audit integration" documented in the integrations directory, alongside the Cursor MCP quickstart. The package `cml/experimental` is explicitly non-normative and hosts evolving research helpers; consumers should treat MCP tool names as subject to change. Source: [cml/experimental/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/experimental/__init__.py).

```mermaid
flowchart LR
    CLI[CLI: cli/main.py] --> Core[cml package: audit, chain, ctag]
    REST[REST API: api/server.py] --> Core
    Store[api/store.py] --> REST
    MCP[MCP Server: cml/integrations/mcp] --> Core
    Demo[scripts/run_mcp_demo_payloads.py] --> MCP
    Deploy[Docker / docker-compose] --> REST
    Agent[AI Agent Runtime] --> MCP
    Script[Operator / CI] --> CLI
```

## Deployment

Deployment artifacts live next to the codebase rather than inside it. `ROADMAP.md` documents a "Hosted Audit API infra" milestone that ships a `Dockerfile`, `docker-compose.yml`, and a deploy guide at `docs/deploy/README.md`. Source: [ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md). Publishing is automated through `.github/workflows/publish-pypi.yml` using Trusted Publishing, which makes the `causal-memory-layer` package a normal PyPI consumer dependency.

For local development, the validation command is `pip install -e ".[dev]" && pytest`. Source: [READY_FOR_REVIEW.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/READY_FOR_REVIEW.md) confirms that a fresh clone passes the documented quickstart (102 passed, 2 skipped) and that CI runs on push and pull request via `.github/workflows/ci.yml`. Reviewer hygiene also requires that no `.env` files, private keys, or tokens are committed — the strings "secret"/"key"/"token" only appear in the SECRET→NET_OUT demo fixtures, which are illustrative. Source: [READY_FOR_REVIEW.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/READY_FOR_REVIEW.md).

## Common Failure Modes

- **Missing required fields.** The CLI rejects lines that lack `id`, `timestamp`, `actor`, `action`, `object`, or `permitted_by`, or that carry a boolean in `timestamp`. Source: [cli/main.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cli/main.py).
- **Causally invalid actions.** A trace can be operationally correct and still fail audit rules such as `CML-AUDIT-R3-SECRET_NET_MISSING_CHAIN`. Source: [demos/secret_to_network_causal_invalid/README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/demos/secret_to_network_causal_invalid/README.md).
- **Treating experimental APIs as stable.** Anything under `cml/experimental` (and the MCP tool surface itself) is non-normative. Source: [cml/experimental/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/experimental/__init__.py).
- **API regression risk.** Without smoke tests the FastAPI surface can drift silently — community issue #47 tracks adding `GET /health`, `POST /audit`, and CTAG decode coverage. Source: community issue [#47](https://github.com/safal207/Causal-Memory-Layer/issues/47).

## See Also

- [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md) — project overview and quickstart
- [ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md) — release and deployment milestones
- [vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md) — vCML record schema
- [CONTRIBUTING.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/CONTRIBUTING.md) — pull request checklist

---

<a id='page-4'></a>

## vCML Reference Implementation, LLM Integrations and Research Directions

### Related Pages

Related topics: [Introduction to CML](#page-1), [Causal Records, Chains, CTAG and Audit Rules](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md)
- [ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md)
- [vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md)
- [vcml/linux-ebpf/README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/linux-ebpf/README.md)
- [vcml/hardware/CTAG-8-16.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/hardware/CTAG-8-16.md)
- [cml/record.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/record.py)
- [cml/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py)
- [cml/report.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/report.py)
- [scripts/run_safety_eval.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/scripts/run_safety_eval.py)
- [integrations/vscode-cml/package.json](https://github.com/safal207/Causal-Memory-Layer/blob/main/integrations/vscode-cml/package.json)
- [integrations/vscode-cml/src/extension.ts](https://github.com/safal207/Causal-Memory-Layer/blob/main/integrations/vscode-cml/src/extension.ts)
- [CONTRIBUTING.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/CONTRIBUTING.md)
- [LICENSE_COMMERCIAL.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/LICENSE_COMMERCIAL.md)
</details>

# vCML Reference Implementation, LLM Integrations and Research Directions

## Overview

The Causal Memory Layer (CML) is an open-source causal audit layer for structured action traces. The project deliberately scopes itself to a single primitive — *causal-validity checking* — and explicitly does not claim to solve AI safety, security, or compliance in general. Its core value proposition is captured in the project statement: "A system may be functionally correct while being causally invalid. CML exists to make that distinction inspectable." Source: [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md).

The repository ships a working Python SDK, an HTTP API, a CLI, a VS Code extension, an optional Linux eBPF reference path under `vcml/`, deterministic LLM provider mappings, a safety-eval benchmark, and a series of demos. The current artifact list is enumerated in [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md) and includes `cml/audit.py`, `cml/chain.py`, `cli/main.py`, `api/server.py`, the provider demo scripts under `examples/`, and the corresponding test files `tests/test_audit.py`, `tests/test_agent_approval_lineage_demo.py`, and `tests/test_api_smoke.py`.

## vCML Reference Implementation

### Record Format

The vCML Causal Record Format is defined in [vcml/FORMAT.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/FORMAT.md) as a minimal semantic structure describing *what must be remembered*, not how it is transported or stored. Its design principles are append-only, immutable-once-written, language-agnostic, transport-agnostic, and storage-agnostic. The record captures **permission and responsibility, not outcomes**. The required fields are `id`, `timestamp`, `actor`, `action`, `object`, `permitted_by` (a semantic reference, not enforcement logic), and `parent_cause` (the identifier enabling causal chain reconstruction). A future `integrity` placeholder is reserved for hash or signature.

The Python implementation is provided by [cml/record.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/record.py), which defines the `CausalRecord` dataclass, an `Actor` dataclass (pid, uid, ppid, gid, comm), and canonical `Action` constants: `EXEC`, `OPEN`, `READ`, `WRITE`, `CONNECT`, `SEND`. The top-level package surface is consolidated in [cml/__init__.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/cml/__init__.py), which re-exports `load_jsonl`, `records_to_index`, `CTAGState`, `compute_ctag`, `decode_ctag`, `reconstruct_chain`, `has_path`, `find_root`, `AuditEngine`, `AuditConfig`, `Finding`, `Severity`, `CustomRule`, and the report helpers `to_markdown`, `to_json`, and `to_text`.

### Linux eBPF Reference Path

The eBPF reference path is documented in [vcml/linux-ebpf/README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/linux-ebpf/README.md) and is described as one possible implementation, chosen because Linux dominates servers, cloud, containers, and open-source systems. eBPF allows OS-adjacent instrumentation without kernel-source modification or heavy modules, providing precise access to syscall boundaries. The first targeted boundary is process execution (`exec`) because it has clear parent-child relationships and minimal ambiguity.

The reference implementation uses the BCC framework to attach to the `sched:sched_process_exec` tracepoint, capture execution events (PID, PPID, filename), maintain a user-space `PID → CausalID` mapping, and emit JSONL records containing `parent_cause`. Runtime requirements: Linux kernel with `CONFIG_BPF_SYSCALL`, root privileges, `python3-bpfcc`, and kernel headers matching the running kernel.

```mermaid
flowchart LR
  A[Syscall Boundary<br/>sched:sched_process_exec] --> B[eBPF Probe<br/>BCC]
  B --> C[Capture pid / ppid / comm]
  C --> D[User-Space PID → CausalID Map]
  D --> E[JSONL Causal Record<br/>with parent_cause]
  E --> F[AuditEngine.run]
  F --> G[AuditResult + Findings<br/>to_markdown / to_json]
```

## LLM Provider Integrations

The LLM Provider Interoperability milestone in [ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md) is marked complete and demonstrates that CML preserves a single verifiable causal model across different LLM tool-calling protocols without changing the core schema. Deterministic provider-specific causal-audit mappings and example traces are maintained for seven ecosystems: OpenAI, Claude, Gemini, Grok / xAI, Qwen, Kimi, and DeepSeek. A unified matrix is published in `docs/integrations/LLM_PROVIDER_MATRIX.md`.

The roadmap explicitly separates two identifier categories:
- **Provider correlation IDs** — `call_id`, `tool_use_id`, `functionCall.id`, `tool_call_id`
- **CML causal authorization** — `parent_cause`, `permitted_by`, approval ancestry

For Kimi and Gemini, reasoning-related state is preserved only as safe handling metadata or digest; raw reasoning is never published. The milestone is intentionally SDK-independent and non-normative: it does not perform real model calls or tool executions in tests, and it does not constitute an official provider endorsement. Source: [ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md).

A VS Code extension at [integrations/vscode-cml/](https://github.com/safal207/Causal-Memory-Layer/blob/main/integrations/vscode-cml/package.json) exposes three commands — `cml.auditCurrentLog`, `cml.showChainForSelectedRecord`, and `cml.auditExampleLog` — and, per [integrations/vscode-cml/src/extension.ts](https://github.com/safal207/Causal-Memory-Layer/blob/main/integrations/vscode-cml/src/extension.ts), delegates all heavy lifting to the local Python CLI as the source of truth.

## Research Directions

### Signed Causal Receipts with Temporal Provenance

Community research (Issue #139) proposes extending CML beyond causal validity to proof of authorship. The framing is: *CML verifies causality. Signed receipts add proof of authorship. Temporal provenance adds a time anchor.* The format already reserves an `integrity` field for hash or signature. Issue #141 reports that the `Security Baseline` secret-scan job failed on `main` after the research note was merged, an early signal of friction between research artifacts and the secret-scanning policy on the protected branch.

### Hardware CTAG Mapping

The 16-bit Causal Tag (CTAG) is being mapped to hardware metadata in [vcml/hardware/CTAG-8-16.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/vcml/hardware/CTAG-8-16.md). A compact 8-bit variant (CTAG-8) targets cache line tags, DRAM metadata, and embedded MCUs, packing DOM (3 bits), CLASS (3 bits), GEN parity (1 bit), and SEAL (1 bit), with LHINT dropped. The motivation is that carrying CTAG in hardware makes causal memory zero-copy and near-zero-overhead, paying the semantic cost of causality once at design time.

### Safety-Eval Benchmark and Approval Lineage

A deterministic safety-eval benchmark ships with fixtures under `benchmarks/fixtures/` and is runnable through [scripts/run_safety_eval.py](https://github.com/safal207/Causal-Memory-Layer/blob/main/scripts/run_safety_eval.py), which supports a `--markdown-out` snapshot flag. The v0.4.1 release introduced the Approval Lineage Demo, which detects agent actions that succeed operationally but lack valid upstream approval lineage. The v0.5.1 release added read-only audit semantics including causal gap detection and SECRET → NET_OUT validation, framed as a meaning-only layer with no enforcement.

### Community-Driven Gaps

Open community issues continue to shape the surface area. Issue #47 tracks API smoke tests for `GET /health`, `POST /audit`, and CTAG decode, complementing the existing `tests/test_api_smoke.py` referenced in [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md). Issues #65 and #66 propose a plain-language audit findings glossary, a natural follow-on for translating the engine's R1–R4 findings into human-readable guidance. Source: [CONTRIBUTING.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/CONTRIBUTING.md) for contribution conventions.

## See Also

- [README.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/README.md) — repository overview, quickstart, current artifact list
- [ROADMAP.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/ROADMAP.md) — milestone history and forthcoming work
- [CONTRIBUTING.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/CONTRIBUTING.md) — pull request checklist and communication norms
- [LICENSE_COMMERCIAL.md](https://github.com/safal207/Causal-Memory-Layer/blob/main/LICENSE_COMMERCIAL.md) — Open Core licensing tiers

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: safal207/Causal-Memory-Layer

Summary: Found 11 structured pitfall item(s), including 2 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

## 1. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/safal207/Causal-Memory-Layer/issues/139

## 2. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/safal207/Causal-Memory-Layer/issues/66

## 3. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: packet_text.keyword_scan | https://github.com/safal207/Causal-Memory-Layer

## 4. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/safal207/Causal-Memory-Layer

## 5. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/safal207/Causal-Memory-Layer

## 6. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/safal207/Causal-Memory-Layer

## 7. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/safal207/Causal-Memory-Layer

## 8. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/safal207/Causal-Memory-Layer/issues/141

## 9. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/safal207/Causal-Memory-Layer/issues/47

## 10. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/safal207/Causal-Memory-Layer

## 11. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/safal207/Causal-Memory-Layer

<!-- canonical_name: safal207/Causal-Memory-Layer; human_manual_source: deepwiki_human_wiki -->