Metadata-Version: 2.4
Name: memorylens
Version: 0.1.0
Summary: Observability and debugging for AI agent memory systems
Author: MemoryLens Contributors
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: opentelemetry-api>=1.20
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20
Requires-Dist: opentelemetry-sdk>=1.20
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9
Provides-Extra: audit
Requires-Dist: numpy>=1.24; extra == 'audit'
Requires-Dist: sentence-transformers>=2.0; extra == 'audit'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: numpy>=1.24; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1; extra == 'langchain'
Provides-Extra: letta
Requires-Dist: letta-client>=0.1; extra == 'letta'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10; extra == 'llamaindex'
Provides-Extra: mem0
Requires-Dist: mem0ai>=0.1; extra == 'mem0'
Provides-Extra: ui
Requires-Dist: fastapi>=0.110; extra == 'ui'
Requires-Dist: jinja2>=3.1; extra == 'ui'
Requires-Dist: python-multipart>=0.0.9; extra == 'ui'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'ui'
Provides-Extra: zep
Requires-Dist: zep-python>=2.0; extra == 'zep'
Description-Content-Type: text/markdown

# MemoryLens

**Observability and debugging for AI agent memory systems.**

MemoryLens instruments the memory pipeline in your AI agents — write, read, compress, update — and gives you full visibility into what's happening. No more guessing why your agent "forgot" something.

## Install

```bash
pip install memorylens

# With framework integrations
pip install memorylens[langchain]
pip install memorylens[mem0]
```

## Quick Start

```python
import memorylens
from memorylens import instrument_write, instrument_read, context

# Initialize (defaults to local SQLite storage)
memorylens.init()

# Decorate your memory functions
@instrument_write(backend="my_db")
def store(content: str) -> bool:
    # your existing code
    return True

@instrument_read(backend="my_db")
def search(query: str) -> list[str]:
    # your existing code
    return ["result"]

# Add context for session tracking
with context(agent_id="support-bot", session_id="sess-123", user_id="user-456"):
    store("user prefers vegetarian meals")
    results = search("dietary preferences")

# Inspect with the CLI
# memorylens traces list
# memorylens traces show <trace-id>
```

## Auto-Instrumentation

For supported frameworks, zero code changes required:

```python
import memorylens

memorylens.init(instrument=["langchain", "mem0"])
# All memory operations are now traced automatically
```

## CLI

```bash
memorylens init                          # Set up local storage
memorylens traces list                   # List recent traces
memorylens traces list --status error    # Filter by status
memorylens traces show <trace-id>        # Inspect a trace
memorylens traces export -o traces.jsonl # Export as JSONL
memorylens stats                         # Summary statistics
```

## OTLP Export

Send traces to any OpenTelemetry-compatible backend:

```python
memorylens.init(
    exporter="otlp",
    otlp_endpoint="http://localhost:4317",
)
```

Or use environment variables:

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_SERVICE_NAME=my-agent
```

## Community Integrations

Want to add support for a new memory framework? See the [Instrumentation Spec v1](docs/instrumentation-spec-v1.md) for the protocol, required span attributes, implementation patterns, and a complete working example.

Validate your integration with:

```bash
memorylens validate integration my_package.instrumentor
```

## License

Apache 2.0
