Metadata-Version: 2.4
Name: memledger
Version: 2.0.0
Summary: Memory governance and trust layer for AI agents — provenance, attribution, confidence gating
Project-URL: Homepage, https://memledger.com
Project-URL: Documentation, https://memledger.com/docs
Author: Ratnopam Chakrabarti
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.10
Requires-Dist: litellm>=1.40.0
Requires-Dist: neo4j>=5.27
Requires-Dist: numpy>=1.24.0
Requires-Dist: opentelemetry-api>=1.20
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20
Requires-Dist: opentelemetry-sdk>=1.20
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9.0
Provides-Extra: all
Requires-Dist: aiosqlite>=0.19.0; extra == 'all'
Requires-Dist: arize-phoenix-client>=2.0; extra == 'all'
Requires-Dist: arize-phoenix-otel>=0.6; extra == 'all'
Requires-Dist: asyncpg>=0.29.0; extra == 'all'
Requires-Dist: boto3>=1.35.0; extra == 'all'
Requires-Dist: datasets>=2.0.0; extra == 'all'
Requires-Dist: fastembed<1.0,>=0.5; extra == 'all'
Requires-Dist: httpx>=0.27.0; extra == 'all'
Requires-Dist: langchain-community>=0.3.0; extra == 'all'
Requires-Dist: langchain>=0.3.0; extra == 'all'
Requires-Dist: langgraph-checkpoint>=2.0.0; extra == 'all'
Requires-Dist: langgraph>=0.2.0; extra == 'all'
Requires-Dist: matplotlib>=3.7.0; extra == 'all'
Requires-Dist: mcp>=1.0.0; extra == 'all'
Requires-Dist: opensearch-py>=2.4.0; extra == 'all'
Requires-Dist: pgvector>=0.3.0; extra == 'all'
Requires-Dist: ragas>=0.2.0; extra == 'all'
Requires-Dist: sqlite-vec>=0.1.0; extra == 'all'
Provides-Extra: aws
Requires-Dist: asyncpg>=0.29.0; extra == 'aws'
Requires-Dist: boto3>=1.35.0; extra == 'aws'
Requires-Dist: pgvector>=0.3.0; extra == 'aws'
Provides-Extra: bedrock
Requires-Dist: boto3>=1.35.0; extra == 'bedrock'
Provides-Extra: dev
Requires-Dist: aiosqlite>=0.19.0; extra == 'dev'
Requires-Dist: boto3>=1.35.0; extra == 'dev'
Requires-Dist: fastembed<1.0,>=0.5; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Provides-Extra: dynamodb
Requires-Dist: boto3>=1.35.0; extra == 'dynamodb'
Provides-Extra: eval
Requires-Dist: arize-phoenix-client>=2.0; extra == 'eval'
Requires-Dist: datasets>=2.0.0; extra == 'eval'
Requires-Dist: langchain-community>=0.3.0; extra == 'eval'
Requires-Dist: langchain>=0.3.0; extra == 'eval'
Requires-Dist: matplotlib>=3.7.0; extra == 'eval'
Requires-Dist: ragas>=0.2.0; extra == 'eval'
Provides-Extra: langgraph
Requires-Dist: langgraph-checkpoint>=2.0.0; extra == 'langgraph'
Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
Provides-Extra: local
Requires-Dist: fastembed<1.0,>=0.5; extra == 'local'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: opensearch
Requires-Dist: boto3>=1.35.0; extra == 'opensearch'
Requires-Dist: httpx>=0.27.0; extra == 'opensearch'
Requires-Dist: opensearch-py>=2.4.0; extra == 'opensearch'
Provides-Extra: oss
Requires-Dist: asyncpg>=0.29.0; extra == 'oss'
Requires-Dist: fastembed<1.0,>=0.5; extra == 'oss'
Requires-Dist: pgvector>=0.3.0; extra == 'oss'
Provides-Extra: pgvector
Requires-Dist: asyncpg>=0.29.0; extra == 'pgvector'
Requires-Dist: pgvector>=0.3.0; extra == 'pgvector'
Provides-Extra: sqlite
Requires-Dist: aiosqlite>=0.19.0; extra == 'sqlite'
Requires-Dist: sqlite-vec>=0.1.0; extra == 'sqlite'
Provides-Extra: telemetry
Requires-Dist: arize-phoenix-otel>=0.6; extra == 'telemetry'
Description-Content-Type: text/markdown

# memledger

**Memory governance and trust layer for multi-agent AI systems.**

memledger adds attribution, provenance, confidence gating, and quality measurement on top of any vector-backed memory store. Every memory carries a source, a confidence score, a derivation chain, and an audit trail — so when agents share memory, trust transfers become legible instead of invisible.

> ✅ **v2.0.0 — AWS-native release.** Stable API; subsequent releases follow [SemVer](https://semver.org/).

## Why memledger

Existing memory frameworks (Mem0, Zep, Letta, AgentCore Memory) optimize for *recall quality* — how accurately the system retrieves relevant memory. None of them address *accountability*: who wrote this memory, how confident were they, what did they derive it from, and how has it been used since.

In a single-agent system, the accountability gap is academic. In a multi-agent system where agents read and act on each other's beliefs, it is the fault line where systems fail at scale.

## What v2.0.0 ships

- **Attribution** — every memory carries `created_by`, `confidence`, `session_id`, `derived_from`, `supersedes`, `workflow_id`, `triggered_by`, `hedged`, `namespace`
- **Weakest-link provenance chain** — derivation chains tracked across agent boundaries; effective confidence for retrieval is `min(declared, chain.min_confidence)` — a high-conf claim built on a low-conf ancestor cannot outscore its weakest link
- **Confidence-gated retrieval** — `PASS` / `FLAG` / `FILTER` policy applied at search time, against effective confidence
- **Namespace RBAC** — declarative per-agent access control over hierarchical namespaces; `add()` and `search()` both gate on it
- **3-tier evaluation suite** — deterministic Memory Attribution Integrity (record-quality view) + RAGAS LLM-as-judge (provider-agnostic via LiteLLM; verified end-to-end on Bedrock Sonnet) + structural evaluator (OTEL-span based, no LLM)
- **AWS-native backends** — Aurora PostgreSQL with IAM auth, OpenSearch with SigV4 + faiss + hybrid RRF, Bedrock for embeddings (Titan v2) and the LLM strategy layer (Sonnet)
- **OpenTelemetry observability** — every operation emits an OTLP span with `memledger.*` trust attributes; tier-1 set to OpenInference span kinds so [Arize Phoenix](https://github.com/Arize-ai/phoenix) categorizes them out of the box
- **Outcome feedback loop** — `record_outcome()` updates memory confidence based on observed downstream outcomes
- **MCP server** — framework-agnostic adoption via Model Context Protocol

Full architecture, concepts, and API reference at [memledger.com/docs](https://memledger.com/docs).

## Install

The OSS-default install needs **no cloud credentials**:

```bash
pip install 'memledger[oss]'
```

The AWS-native install:

```bash
pip install 'memledger[aws]'                # Aurora pgvector + Bedrock
pip install 'memledger[aws,opensearch]'     # add OpenSearch backend
```

Other extras (combine as needed):

| Extra | Use |
|---|---|
| `[oss]` | Local ONNX embeddings + Postgres + pgvector — no cloud keys |
| `[aws]` | Aurora pgvector + Bedrock embeddings + Bedrock judge |
| `[opensearch]` | Amazon OpenSearch backend (SigV4 + faiss + hybrid RRF) |
| `[eval]` | RAGAS LLM-as-judge (Tier 2 of the eval suite) |
| `[telemetry]` | Phoenix-OTEL helper on top of the core OTEL stack |
| `[mcp]` | MCP server for framework-agnostic adoption |

**Backend contract:** the only required backend is **open-source PostgreSQL ≥ 14 with the [pgvector](https://github.com/pgvector/pgvector) extension ≥ 0.5**. Aurora, RDS, Supabase, Neon — same backend, only the DSN changes.

## Quick start (60 seconds)

```bash
# 1. Postgres + pgvector locally
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres pgvector/pgvector:pg16

# 2. Install
pip install 'memledger[oss]'
```

```python
# 3. Write + search one memory
import asyncio
from memledger import Memledger

async def main():
    ml = await Memledger.create(
        backend_name="pgvector",
        connection_string="postgresql://postgres:postgres@localhost:5432/postgres",
    )
    await ml.add(
        content="HikariCP maxPoolSize=50 fixes payment-service OOM",
        namespace="/ops/incidents/payment-svc",
        confidence=0.9,
        created_by="ops-agent",
    )
    results = await ml.search(
        query="connection pool fix",
        namespace="/ops/incidents/payment-svc",
    )
    for r in results.records:
        print(r.confidence, r.created_by, "::", r.content)
    await ml.close()

asyncio.run(main())
```

For multi-agent walkthroughs (weakest-link gate, contamination interception, eval pipeline), see [memledger.com/docs/concepts/provenance-chain](https://memledger.com/docs/concepts/provenance-chain).

## CLI

```bash
memledger init                                  # write a starter memledger.yaml
memledger add "fact" --namespace /n --agent-id a --confidence 0.8
memledger search "query" --namespace /n --confidence-min 0.6
memledger get <memory-id> --chain
memledger eval <session-id>
memledger status
```

`memledger --help` for the full surface.

## Roadmap

| Version | What |
|---|---|
| **v2.0** (this release) | AWS-native trust layer; 3-tier eval suite; weakest-link confidence; namespace RBAC; MCP |
| **v2.1** (Jun 15) | DynamoDB backend with composition; LangGraph + OpenAI Agents SDK adapters; memledger lint CLI |
| **v2.2** (Jun 30) | Mem0 + Letta backend adapters; DeepEval + Phoenix Evals adapters |
| **v3.0** (Jul 15) | Eval feedback flywheel — outcomes drive automated memory promote/demote |

## License & support

Apache 2.0. License file ships in the PyPI sdist. For enterprise inquiries, repository access requests, or security disclosures, visit [memledger.com](https://memledger.com).
