MemLens

Open-source memory observability and introspection layer for LLM agents

Debug what your AI agent remembers.

---

Topics

llm agent memory observability introspection ai artificial-intelligence langchain mem0 claude codex grok cursor langgraph tracing debugging production monitoring

Description

MemLens is an open-source memory observability and introspection layer for LLM agents. It provides visibility into what your agent remembers, why it remembers it, and how that memory affects behavior across sessions. MemLens fills the critical gap between tracing LLM calls and understanding memory state in production AI systems.

Why MemLens?

You can trace every LLM call, but you have no idea what your agent remembers.

When an agent gives a wrong answer in production, teams cannot determine if it was a model failure or a memory failure — because memory extraction, retrieval, and belief state are completely invisible.

The Problem in Production

INFRASTRUCTURE  → latency, uptime, errors        [✅ Solved by APM tools]
LLM CALLS       → tokens, costs, quality        [✅ Solved by LangSmith, etc.]
AGENT BEHAVIOR  → tool use, reasoning chains     [✅ Solved by agent tracing]
MEMORY STATE    → what was extracted, stored,     [❌ ALMOST NO TOOLING]
                  retrieved, believed

MemLens fills this critical gap by providing memory observability — the ability to see, understand, and debug what your agent remembers.

Who Needs MemLens?

• AI Engineers building production agents with Claude Code, Codex, Grok, Cursor, LangGraph, or custom frameworks
• DevOps/SRE teams monitoring agent health and memory drift
• Compliance officers in regulated industries requiring audit trails
• AI Researchers studying memory system behavior
• Open-source contributors building the next generation of agent frameworks

---

Features

Write-Side Tracing

Log every memory extraction decision with full visibility:

• What was stored vs. dropped
• Importance scores and confidence levels
• Deduplication decisions
• LLM reasoning for each decision
• Extraction latency metrics

Read-Side Tracing

Log every memory retrieval with complete transparency:

• What was returned vs. rejected
• Relevance scores and ranking
• Retrieval strategy used
• Query-to-result mapping

Belief State Snapshots

Query what the system believes about any user at any time:

• Total memories and type distribution
• Top memories by importance
• Detected contradictions
• Confidence distribution
• Temporal range of memories

Causal Linkage

Trace any wrong response backward to its memory origins:

• Response → Retrieved memories → Extraction decisions → Original sessions
• Identify whether failures are model-level or memory-level
• Root-cause analysis for production incidents

Memory Health Dashboard

Monitor memory system health in real-time:

• Memory drift detection over time
• Contradiction rate tracking
• Staleness scores
• Latency trends and percentiles
• Extraction quality metrics

---

Quick Start

1. Install MemLens

pip install memlens

2. Start the Server

python -m memlens.api.main
# Server running at http://localhost:8000

3. Use the SDK

import asyncio
from memlens.sdk import MemLensClient

async def main():
    # Initialize client
    client = MemLensClient("http://localhost:8000")

    # Trace a memory write
    trace = await client.create_write_trace({
        "session_id": "session_123",
        "user_id": "user_456",
        "agent_id": "agent_1",
        "candidates": [...],
        "stored_memories": [...],
    })

    # Get belief state
    belief = await client.get_belief_state("user_456")
    print(f"Agent believes: {belief['top_memories']}")

asyncio.run(main())

4. Open the Dashboard

Open memlens/dashboard/index.html in your browser to view memory health metrics, traces, and belief states.

---

How to Use

With Claude Code

from memlens.sdk import MemLensClient, memlens_trace

memlens = MemLensClient("http://localhost:8000")

@memlens_trace(user_id="user_123", agent_id="claude_code")
async def process_with_claude(user_input: str):
    # Your Claude Code logic here
    # MemLens automatically traces memory operations
    pass

With Codex

from memlens.integrations import BaseIntegration

class CodexIntegration(BaseIntegration):
    async def wrap_memory_add(self, user_id: str, context: dict):
        # Wrap Codex memory operations
        return await self.memlens.create_write_trace({...})

With Grok

from memlens.sdk import MemLensClient

memlens = MemLensClient("http://localhost:8000")

# Trace Grok memory operations
await memlens.create_write_trace({
    "session_id": grok_session_id,
    "user_id": user_id,
    "agent_id": "grok",
    "candidates": extracted_memories,
})

With Cursor

from memlens.sdk import MemLensClient

memlens = MemLensClient("http://localhost:8000")

# Trace Cursor's memory operations
await memlens.create_write_trace({
    "session_id": cursor_session_id,
    "user_id": user_id,
    "agent_id": "cursor",
    "candidates": cursor_memories,
})

With LangGraph

from memlens.sdk import MemLensClient
from langgraph.graph import StateGraph

memlens = MemLensClient("http://localhost:8000")

# Integrate with LangGraph nodes
async def memory_node(state: dict):
    # Your LangGraph memory logic
    await memlens.create_write_trace({...})
    return state

With Custom Agents

from memlens.sdk import MemLensClient

memlens = MemLensClient("http://localhost:8000")

class MyCustomAgent:
    async def add_memory(self, user_id: str, content: str):
        # Your custom memory logic
        # Trace with MemLens
        await memlens.create_write_trace({
            "session_id": self.session_id,
            "user_id": user_id,
            "agent_id": "custom_agent",
            "candidates": [...],
        })

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Agent Application                         │
│  ┌─────────────┐  ┌─────────────┐  ┌───────────────────── │
│  │ Claude Code │  │   Codex      │  │   Custom Agent      │ │
│  │   Cursor    │  │   Grok       │  │   LangGraph         │ │
│  └──────┬──────┘  └──────┬──────  └──────────┬────────── │
│         └─────────────────┼─────────────────────┘             │
│                         │                                   │
│              ┌──────────▼──────────┐                        │
│              │   MemLens Wrapper    │                        │
│              │  (Instrumentation    │                        │
│              │   & Interception)    │                        │
│              └──────────┬───────────┘                        │
│                         │                                   │
│         ┌───────────────┼───────────────┐                  │
│         │               │               │                   │
│    ┌────▼────┐    ┌────▼────┐    ┌────▼────┐              │
│    │ Write   │    │ Read    │    │ Belief  │              │
│    │ Traces  │    │ Traces  │    │ State   │              │
│    └────┬────┘    └────┬────┘    └────┬────┘              │
│         │               │               │                   │
│         └───────────────┼───────────────┘                  │
│                         │                                   │
│              ┌──────────▼──────────┐                        │
│              │   MemLens Storage    │                        │
│              │  (SQLite/Postgres    │                        │
│              │   + Time-series DB)   │                        │
│              └──────────┬───────────                        │
│                         │                                   │
│              ┌──────────▼──────────┐                        │
│              │   MemLens Dashboard  │                        │
│              │  (Web UI for memory  │                        │
│              │   introspection)     │                        │
│              └─────────────────────┘                        │
└─────────────────────────────────────────────────────────────┘

---

Integrations

Mem0

from memlens.integrations import Mem0Integration

memlens = MemLensClient()
mem0 = Mem0Client()

integration = Mem0Integration(mem0, memlens)
await integration.wrap_memory_add(user_id="user_123", messages=[...])

LangChain

from memlens.integrations import LangChainIntegration

memlens = MemLensClient()
langchain_memory = ConversationBufferMemory()

integration = LangChainIntegration(langchain_memory, memlens)
await integration.wrap_memory_add(user_id="user_123", inputs={"input": "...", "output": "..."})

---

API Endpoints

Endpoint	Method	Description
/health	GET	Health check
/traces/write	POST	Create write trace
/traces/write/{id}	GET	Get write trace
/traces/read	POST	Create read trace
/traces/read/{id}	GET	Get read trace
/belief-state/{user_id}	GET	Get belief state
/belief-state/{user_id}/health	GET	Get health metrics
/causal-chain/{response_id}	GET	Get causal chain

---

Documentation

• Agent Integration Guide — executable instructions and prompts for coding agents
• Quick Start Guide
• API Reference
• Architecture Guide
• Integration Guide
• Contributing

---

Development

Setup

git clone https://github.com/grimdalltech/MemLens.git
cd MemLens
pip install -e ".[dev]"

Run Tests

pytest

Run Server

python -m memlens.api.main

---

Roadmap

• Core tracing engine
• SQLite storage
• FastAPI server
• Python SDK
• Mem0 integration
• LangChain integration
• Web dashboard
• PostgreSQL support
• Memory drift detection
• Advanced analytics
• Enterprise features

---

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

---

License

MIT License - see LICENSE for details.

---

MemLens — Because you can't fix what you can't see.