Metadata-Version: 2.4
Name: codeledger-ai
Version: 0.1.6
Summary: Persistent memory, code provenance, and quality verification for AI coding agents
Project-URL: Homepage, https://github.com/codeledgerAI/codeledger
Project-URL: Repository, https://github.com/codeledgerAI/codeledger
Project-URL: Documentation, https://github.com/codeledgerAI/codeledger/blob/main/README.md
Project-URL: Bug Tracker, https://github.com/codeledgerAI/codeledger/issues
Project-URL: Changelog, https://github.com/codeledgerAI/codeledger/blob/main/CHANGELOG.md
Author-email: CodeLedgerAI <hello@codeledgerai.github.io>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent-memory,ai-memory,claude-code,code-provenance,codebase-memory,cursor,developer-tools,mcp,windsurf
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Version Control
Requires-Python: >=3.11
Requires-Dist: aiosqlite~=0.20.0
Requires-Dist: argon2-cffi~=23.1.0
Requires-Dist: click~=8.1.0
Requires-Dist: cryptography>=46.0.6
Requires-Dist: fastapi>=0.119.0
Requires-Dist: fastmcp>=3.2.0
Requires-Dist: httpx~=0.28.0
Requires-Dist: keyring~=25.0
Requires-Dist: ollama~=0.4.0
Requires-Dist: pgvector~=0.3.0
Requires-Dist: pyjwt>=2.12.0
Requires-Dist: pywin32>=307; sys_platform == 'win32'
Requires-Dist: rank-bm25~=0.2.2
Requires-Dist: slowapi~=0.1.9
Requires-Dist: sqlite-vec<0.2,>=0.1.6
Requires-Dist: tree-sitter-language-pack~=1.6
Requires-Dist: tree-sitter~=0.25.0
Requires-Dist: uvicorn>=0.34
Requires-Dist: watchdog~=6.0
Provides-Extra: benchmark
Requires-Dist: datasets>=2.0.0; extra == 'benchmark'
Requires-Dist: requests>=2.28.0; extra == 'benchmark'
Provides-Extra: dev
Requires-Dist: mypy~=1.14.0; extra == 'dev'
Requires-Dist: pip-audit~=2.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio~=0.25.0; extra == 'dev'
Requires-Dist: pytest-cov~=6.0; extra == 'dev'
Requires-Dist: pytest~=8.3.0; extra == 'dev'
Requires-Dist: ruff~=0.9.0; extra == 'dev'
Provides-Extra: local-embed
Requires-Dist: sentence-transformers~=3.0; extra == 'local-embed'
Provides-Extra: postgres
Requires-Dist: asyncpg~=0.30.0; extra == 'postgres'
Provides-Extra: tiktoken
Requires-Dist: tiktoken~=0.8.0; extra == 'tiktoken'
Description-Content-Type: text/markdown

![License](https://img.shields.io/badge/license-Apache%202.0-green)
![Python](https://img.shields.io/badge/python-3.11+-blue)
![Tests](https://img.shields.io/badge/tests-1062%20passing-green)

# CodeLedger

**Ask why any function exists. Get the decision that created it.**

CodeLedger is an MCP server that gives AI coding agents persistent
memory, bidirectional code provenance, and independent quality
verification. It works with Claude Code, Cursor, Windsurf, and any
MCP-compatible client. Free forever for solo developers. Apache 2.0.

## See it in action

<!-- Demo GIF goes here — record with: asciinema rec demo.cast -->
<!-- Convert to GIF with: agg demo.cast demo.gif -->
<!-- Then: ![CodeLedger provenance demo](docs/demo.gif) -->

```bash
$ provenance.reverse("backend/auth/auth_service.py", "hash_password")
decision   Use Argon2id for all password hashing
recorded   Apr 10 · claude-code · session sess_a1b2
rationale  OWASP 2024 recommendation, memory-hard, GPU-resistant
commit     a1b2c3d — [P1] Auth service with Argon2id hashing
changes    hash_password (added), verify_password (added)
verified   CI passed · run #9912 · Apr 10 10:12

$ drift.check("my-saas-project")
warning    backend/cache/redis.py imports asyncpg directly
violates   decision dec_007: "All DB access through db_backend.py"
```

## Quick start

Requires Node.js 18+. Python 3.11+ installed automatically.

```bash
npx codeledger-ai@latest init-and-serve
```

Open http://localhost:8100 — a 5-step walkthrough gets you to your
first provenance query in under 5 minutes.

Works with: Claude Code · Cursor · Windsurf · Any MCP client
Runs on: Windows · macOS · Linux
Backends: Git and non-git projects

## What CodeLedger does

### Bidirectional code provenance
Every architectural decision links to the exact code it produced —
down to the AST level. Ask why any function exists and get back the
decision, the commit, and the CI verification.

### Active context injection
Relevant decisions are injected automatically before every session
and every file edit via Claude Code hooks. Your agent knows your
architecture before it types a character. No manual prompting required.

### Independent quality harness
Five sensors — coverage delta, complexity, import health, drift
violations, decision density — running independently of what the
agent reports. Catches tautological tests that prove implementation
instead of specification.

### Architectural drift detection
Compares your import graph against recorded architecture decisions
in real time. Catches violations before they compound into a refactor.

### Rollback impact planning
Before reverting any decision, see the full downstream dependency
graph — which functions break, which decisions become orphaned,
and the risk level.

## How it works

**1. Install once**
```bash
npx codeledger-ai@latest init-and-serve
```
One command on any OS. Python venv, server, and MCP config handled automatically.

**2. Init each project**
```bash
codeledger init
```
Creates config, git hooks, and a project CLAUDE.md that instructs the agent.

**3. Work normally**
Open Claude Code or Cursor. Context is injected automatically. Record
decisions when you make architectural choices.

**4. Query anything**
```bash
provenance.reverse("path/to/file.py", "function_name")
drift.check("project-name")
harness.score("session-id")
```

## What makes CodeLedger different

Most AI memory tools give agents session memory — the ability to
recall past conversations and past context.

CodeLedger does something different: it links decisions to code.

When your agent writes a function, CodeLedger records why — and you
can ask "why does this function exist" and get back the decision,
the commit, and the CI result that verified it.

| Capability | CodeLedger | Typical AI memory tools |
|---|---|---|
| Semantic memory | ✓ | ✓ |
| Decision → code provenance | ✓ | — |
| Reverse trace: code → decision | ✓ | — |
| CI verification linked | ✓ | — |
| Drift detection | ✓ | — |
| Tautological test detection | ✓ | — |
| Rollback impact planning | ✓ | — |
| Auto context injection via hooks | ✓ | partial |

## Installation

### One command (recommended)
```bash
npx codeledger-ai@latest init-and-serve
```
Requires Node.js 18+. Detects or installs Python 3.11+ automatically.

### Custom port
```bash
npx codeledger-ai@latest init-and-serve --port 9000
```

### Team mode
```bash
npx codeledger-ai@latest init-and-serve --mode team
```

### Python directly
```bash
pip install codeledger-ai
cd your-project
codeledger init
codeledger serve
codeledger connect
```

### Per-project setup
Once the server is running, initialise each project:
```bash
cd your-project
codeledger init
```
One server serves all projects simultaneously.

## Configuration

CodeLedger generates `codeledger.toml` in each project directory.
See `codeledger.toml.example` for all options.

Key settings:

```toml
[server]
port = 8100        # change if 8100 is in use
mode = "solo"      # or "team" for shared server

[embedding]
backend = "local"  # or "ollama" for higher quality

[billing]
open_beta = true   # all features free during beta
enabled = false    # set true when Stripe configured
```

## MCP client support

`codeledger connect` auto-configures all detected clients.

| Client | MCP tools | Auto context | File hooks | Auto session |
|---|---|---|---|---|
| Claude Code | ✓ full | ✓ | ✓ | ✓ |
| Cursor | ✓ | ✓ via tool | ✓ via before_edit | ✓ inactivity |
| Windsurf | ✓ | ✓ via tool | ✓ via before_edit | ✓ inactivity |
| Claude Desktop | ✓ | ✓ via tool | ✓ via before_edit | ✓ inactivity |
| Any MCP client | ✓ | ✓ via tool | ✓ via before_edit | ✓ inactivity |

## Contributing

```bash
git clone https://github.com/codeledgerAI/codeledger.git
cd codeledger
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest tests/ -v
```

Before submitting a PR:
- `ruff check .` must pass
- `mypy --strict backend/` must pass
- `pytest tests/ --cov=backend --cov-fail-under=82` must pass
- No new runtime CVEs (`pip-audit`)

See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for full guidelines.

## Security

CodeLedger stores no credentials in its database. All secrets live
in your OS keyring or an AES-256-GCM encrypted vault file. Passwords
are hashed with Argon2id (64MB, 3 iterations, parallelism 4).

See [docs/SECURITY.md](docs/SECURITY.md) for the complete security model.

To report a vulnerability: open a GitHub Security Advisory or email
security@codeledgerai.github.io

## Benchmarks

Retrieval quality measured against LongMemEval-S and LOCOMO datasets.
Results in [scripts/benchmark/README.md](scripts/benchmark/README.md).

Run benchmarks yourself:
```bash
pip install codeledger-ai[benchmark]
codeledger-benchmark run --dataset longmemeval --output results.json
```

## Pricing

**Solo** — Free forever. Full capabilities. Apache 2.0. Self-hosted.
All features available during open beta.

**Team** — $9/seat/month (min 2 seats). Shared decision history,
conflict detection, sprint intelligence. Trigger: shared state,
not seat count.

**Enterprise** — Custom. RBAC, audit export, SSO, SLA.

All features free during open beta.

## License

Apache 2.0 — see [LICENSE](LICENSE) for details.

Copyright 2026 CodeLedgerAI
