Metadata-Version: 2.4
Name: memledger
Version: 1.0.0
Summary: Memory governance and trust layer for AI agents — provenance, attribution, confidence gating
Project-URL: Homepage, https://github.com/memledger-ai/memledger-core
Project-URL: Documentation, https://memledger.dev
Project-URL: Repository, https://github.com/memledger-ai/memledger-core
Project-URL: Issues, https://github.com/memledger-ai/memledger-core/issues
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: 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: boto3>=1.35.0; extra == 'aws'
Requires-Dist: httpx>=0.27.0; extra == 'aws'
Requires-Dist: opensearch-py>=2.4.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: 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.

> ✅ **v1.0.0 — first stable release.** API is stable; subsequent releases follow [SemVer](https://semver.org/). See the [CHANGELOG](https://github.com/memledger-ai/memledger-core/blob/main/CHANGELOG.md) for the v1 contract.

## 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 v1 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 scorer + RAGAS LLM-as-judge (provider-agnostic via LiteLLM) + (optional) AWS Bedrock AgentCore evaluator
- **OpenTelemetry observability** — every operation emits an OTLP span with memory 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 (validated against LangGraph in v1; broader framework coverage in v1.5)

See [docs/architecture.md](https://github.com/memledger-ai/memledger-core/blob/main/docs/architecture.md) for the full design.

## Install

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

```bash
pip install 'memledger[local,pgvector]'
```

Other extras (combine as needed):

| Extra | Use |
|---|---|
| `[local]` | Local ONNX embeddings via fastembed (default — no cloud keys) |
| `[pgvector]` | Postgres + pgvector backend (required for the default path) |
| `[eval]` | RAGAS LLM-as-judge evaluator |
| `[telemetry]` | Phoenix-OTEL helper on top of the core OTEL stack |
| `[mcp]` | MCP server for framework-agnostic adoption |
| `[aws]` | AWS path: Bedrock LLM/embedding, SigV4 OpenSearch, DynamoDB |

**Backend contract (v1):** 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. See [Memory backend contract](https://github.com/memledger-ai/memledger-core/blob/main/docs/architecture.md#memory-backend-contract-v1) for verified Docker / Kubernetes / AWS deployment patterns.

## 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[local,pgvector]'
```

```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 a full multi-agent flow showing the weakest-link gate intercepting a contamination cascade, see the [`examples/multi-agent/`](https://github.com/memledger-ai/memledger-core/tree/main/examples/multi-agent) reference client — five LLM-driven agents over a shared memledger, with Phoenix observability and the deterministic + RAGAS evaluation tiers wired end-to-end.

## 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 |
|---|---|
| **v1.0** (in flight) | Stable API for everything in *What v1 ships* above |
| **v1.5** | Temporal decay wired into the gate; OTEL collector fan-out to Prometheus + Grafana; MCP server validated against CrewAI / AutoGen / LangChain; graph-native chain storage (Apache AGE / Neo4j) behind the existing `ChainStore` interface |
| **v2** | AWS-first integrations (AgentCore evaluations on CloudWatch + OTEL; Bedrock-native eval pipeline; first-class Aurora/OpenSearch backend tuning) |
| **v3 candidate** | **Dreaming** — async memory consolidation, reflection, adaptive forgetting, replay (the G4 "memory patterns" roadmap item) |

## Companion repositories

memledger lives across three repositories under the [memledger-ai](https://github.com/memledger-ai) GitHub organization:

- **[memledger-core](https://github.com/memledger-ai/memledger-core)** — Python SDK, MCP server, Helm chart (this repo)
- **[memledger-ui](https://github.com/memledger-ai/memledger-ui)** — Trust graph visualization (FastAPI + React)
- **[memledger-docs](https://github.com/memledger-ai/memledger-docs)** — Documentation site (Docusaurus)

## Contributing

We accept issues and PRs. See [CONTRIBUTING.md](https://github.com/memledger-ai/memledger-core/blob/main/CONTRIBUTING.md) (lands in v1) and [SECURITY.md](https://github.com/memledger-ai/memledger-core/blob/main/SECURITY.md) for the disclosure policy.

## License

Apache 2.0. See [LICENSE](https://github.com/memledger-ai/memledger-core/blob/main/LICENSE).
