Agent Memory — Integration Guide

AgentLens provides three memory capabilities that turn stateless AI agents into self-improving systems: Recall, Reflect, and Context. This guide covers when and how to use each one.

Note: Lesson capture (the former Learn capability) moved to Lore. Use lore-sdk or the Lore MCP server for saving and managing distilled insights.

Overview

Capability	MCP Tool	API Endpoint	Purpose
Recall	—	GET /api/recall	Semantic search over past events and sessions
Reflect	agentlens_reflect	GET /api/reflect	Analyze behavioral patterns (errors, costs, tool usage, performance)
Context	agentlens_context	GET /api/context	Retrieve cross-session context for a topic

Together, these give agents the ability to:

• Remember what happened in past sessions
• Analyze their own behavioral patterns
• Carry context across session boundaries

Setup

MCP Configuration

Add the AgentLens MCP server to your agent's config. The memory tools are automatically registered alongside the core observability tools.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "agentlens": {
      "command": "npx",
      "args": ["@agentkitai/agentlens-mcp"],
      "env": {
        "AGENTLENS_API_URL": "http://localhost:3400",
        "AGENTLENS_API_KEY": "als_your_key_here",
        "AGENTLENS_AGENT_NAME": "my-agent"
      }
    }
  }
}

API Key

Create an API key if you haven't already:

curl -X POST http://localhost:3400/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'

Embedding Backend

Recall uses vector embeddings for semantic search. Configure the embedding backend via environment variables on the server:

Variable	Default	Description
AGENTLENS_EMBEDDING_BACKEND	openai	Embedding backend (openai)
AGENTLENS_EMBEDDING_MODEL	varies	Model name override
OPENAI_API_KEY	—	Required for the openai backend

• openai — Uses OpenAI's embedding API. Requires OPENAI_API_KEY.

The former bundled local (ONNX) and none backends were removed. For local or alternative embeddings, use Lore for semantic search.

Recall — Semantic Search

Use agentlens_recall when the agent needs to search its memory for relevant past experience.

When to Use

• Before starting a task, check if similar work was done before
• When encountering an error, search for past occurrences
• To find relevant context for decision-making
• To locate related sessions or events

Query Strategies

Broad search — cast a wide net:

agentlens_recall({ query: "authentication", scope: "all" })

Scoped search — narrow to a specific source type:

agentlens_recall({ query: "deployment failures", scope: "events" })

High-confidence only — filter by similarity score:

agentlens_recall({ query: "API timeout", minScore: 0.8 })

Time-bounded — recent history only:

agentlens_recall({ query: "database errors", from: "2026-02-01", to: "2026-02-08" })

What It Returns

Results are ranked by cosine similarity. Each result includes:

• sourceType — event or session
• score — similarity from 0 to 1
• text — the matching content
• metadata — source-specific context (sessionId, category, etc.)

Learn — Moved to Lore

Lesson capture and management (the former agentlens_learn tool and /api/lessons endpoints) have moved to Lore. Use lore-sdk or the Lore MCP server to save, list, update, and search distilled insights.

Reflect — Pattern Analysis

Use agentlens_reflect to analyze behavioral patterns across sessions. This is the agent's self-awareness capability.

Analysis Types

error_patterns

Identifies recurring errors across sessions. Useful for detecting systemic issues.

Returns: error patterns with count, first/last seen, affected sessions, and preceding tool calls.

agentlens_reflect({ analysis: "error_patterns", agentId: "my-agent" })

cost_analysis

Breaks down costs by model and agent. Helps optimize model selection and usage patterns.

Returns: total cost, per-session averages, model breakdown, agent breakdown, and cost trend direction.

agentlens_reflect({ analysis: "cost_analysis", from: "2026-01-01" })

tool_sequences

Identifies common tool usage patterns — which tools are called together and in what order.

Returns: tool chains with frequency, session count, and error rate.

agentlens_reflect({ analysis: "tool_sequences", limit: 20 })

performance_trends

Tracks success rate, duration, and error trends over time.

Returns: current metrics, trend buckets, and an overall assessment (improving, stable, degrading).

agentlens_reflect({ analysis: "performance_trends" })

Scheduling Reflection

Consider running reflection:

• At the start of each session (to load current patterns)
• Periodically (daily/weekly) for trend monitoring
• After a series of errors (to identify systemic issues)
• Before major changes (to establish baselines)

Context — Cross-Session History

Use GET /api/context (or the SDK's getContext) to retrieve a topic-focused view of past sessions and lessons. This is ideal for building system prompts or grounding decisions in historical context.

When to Use

• Building a system prompt with relevant history
• Starting work on a topic the agent has handled before
• Providing context to a new agent about previous work
• Auditing what happened with a specific topic

How It Works

The context endpoint:

1. Finds sessions semantically related to the topic
2. Extracts key events from each session
3. Finds relevant lessons
4. Returns everything ranked by relevance score

const context = await client.getContext({
  topic: 'database migrations',
  agentId: 'my-agent',
  limit: 5,
});

// Use in a system prompt
const systemPrompt = `
You are a database migration assistant.

Previous experience with this topic:
${context.sessions.map(s => `- ${s.summary}`).join('\n')}

Lessons learned:
${context.lessons.map(l => `- ${l.title}: ${l.content}`).join('\n')}
`;

Patterns for Self-Improving Agents

Pattern 1: Pre-Task Recall

Before starting a task, search for relevant past experience:

1. Receive task from user
2. agentlens_recall({ query: "<task description>" })
3. Use recall results to inform approach
4. Execute task
5. If successful, save a lesson to Lore (lore-sdk / Lore MCP)

Pattern 2: Error Recovery with Learning

When an error occurs, check if it's happened before:

1. Error occurs
2. agentlens_recall({ query: "<error message>", scope: "events" })
3. Search Lore for a matching lesson → apply known fix
4. If no lesson → debug and solve
5. Save the fix as a lesson in Lore (lore-sdk / Lore MCP)

Pattern 3: Periodic Self-Reflection

Schedule periodic analysis to identify trends:

1. agentlens_reflect({ analysis: "error_patterns" })
2. If recurring errors found → create preventive lessons
3. agentlens_reflect({ analysis: "performance_trends" })
4. If degrading → investigate and adjust behavior

Pattern 4: Context-Aware Sessions

Start sessions with historical context:

1. User asks about topic X
2. GET /api/context?topic=X
3. Include relevant sessions and lessons in system prompt
4. Proceed with full historical awareness

Pattern 5: Knowledge Distillation

After complex tasks, distill learnings:

1. Complete complex multi-step task
2. Review what worked and what didn't
3. Save a lesson to Lore (lore-sdk / Lore MCP) with `importance: "high"`
4. Future runs start with these lessons pre-loaded

Configuration

Embedding Backends

Backend	Quality	Latency	Cost	Best For
openai	Excellent	Medium	Per-token	Semantic search over events and sessions

Set the backend via AGENTLENS_EMBEDDING_BACKEND=openai (with OPENAI_API_KEY), and optionally override the model with AGENTLENS_EMBEDDING_MODEL. Higher minScore values return fewer but more relevant results.