Lore MCP server

Lore — Universal AI Memory Layer

Your AI agents remember everything. Automatically.

Lore is a cross-agent memory system that stores, connects, and retrieves knowledge across any AI agent — without code changes. Install a hook, and relevant memories appear in every prompt. No agent cooperation needed.

User: "What API rate limits should I use?"

── Lore hook fires (20ms) ──────────────────────────────
🧠 Relevant memories from Lore:
- [0.82] Stripe API returns 429 after 100 req/min — use exponential backoff
- [0.71] Our internal API rate limit is 500 req/min per API key
────────────────────────────────────────────────────────

Agent sees memories + prompt → responds with full context

Features

Universal Memory

remember · recall · forget · list_memories · stats

Store and retrieve memories across any AI agent via MCP tools, REST API, or Python/TypeScript SDK. Semantic search with tier-based TTL, temporal decay, and automatic PII redaction.

Knowledge Graph

graph_query · entity_map · related · extract_facts · list_facts · conflicts

Entities and relationships auto-extracted from memories. Hop-by-hop graph traversal surfaces connected knowledge that pure vector search misses. Atomic fact extraction with automatic conflict detection.

Bi-Temporal Facts & Supersession

supersede · list_at_time · facts_at_time · timeline · provenance · supersession_chain · consolidate_memories

History without deletion. Memories and facts are corrected by superseding them, never deleting — every change appends to an auditable trail. Lore tracks two independent time axes (bi-temporal): valid-time (when a fact was true in the world) and system-time (when Lore learned it), so you can ask "what was canonical — or true about X — as of date Y?". list_at_time / facts_at_time answer as-of queries, timeline walks chronologically adjacent events, and provenance / supersession_chain expose the full correction lineage for a memory or fact.

Graph Visualization

Web UI at /ui/

Interactive D3 force-directed graph of your knowledge base. Entity detail panels, topic clusters, search, and filtering. Runs in the browser — no install required.

Session Continuity

Auto-snapshot + auto-inject — zero agent cooperation

The Session Accumulator automatically captures conversation context and injects relevant session history into every prompt. Deterministic (no LLM needed). Works via hooks — the agent never knows Lore exists.

Recent Activity

recent_activity

Session-aware summary of what happened recently across all projects. Gives agents continuity between conversations without manual context-passing.

Topic Notes

topics · topic_detail

Auto-generated concept hubs that cluster related memories, entities, and facts around recurring themes. See everything Lore knows about a topic in one view.

Export & Snapshot

export · snapshot · snapshot_list · save_snapshot

Full data export in JSON and Markdown formats. Obsidian-compatible output for browsing your knowledge graph in a PKM tool. Snapshots for backup and migration.

Approval UX with Risk Scoring

review_digest · review_connection · lore review list --sort risk

Review discovered knowledge graph connections with computed risk scores. Batch approve/reject with notes, full audit trail of decisions. Sort by risk, confidence, or age.

Guided Bootstrap

lore bootstrap

Single command that validates Python version, Postgres, pgvector, Docker, runs migrations, and verifies server health. Use --fix to auto-remediate missing dependencies.

Multi-Agent Setup

lore setup claude-code · lore setup openclaw · lore setup cursor · lore setup codex

One-command hook installation for all major AI coding agents. Auto-retrieval injected into every prompt — no code changes needed. Includes --validate, --test-connection, and --dry-run flags.

SLO Dashboard + Alerting

lore slo create · lore slo status · GET /v1/slo/status

Define SLO targets for retrieval latency (p50/p95/p99) and hit rate. Background checker evaluates every 60s and fires webhook or email alerts on breach. Time-series API for charting.

Adaptive Retrieval Profiles

lore profiles list · GET /v1/profiles · ?profile=coding

Named retrieval profiles stored in Postgres. Presets for coding (recency-biased), incident response (graph-heavy), and research (long-term). Select per-request or set as API key default.

Policy-Based Retention

lore policy create · lore restore-drill · GET /v1/policies/compliance

Declarative lifecycle policies with per-tier retention windows, cron-based snapshot schedules, and restore drills with timing metrics. Compliance dashboard across all policies.

Multi-Tenant Workspaces

lore workspace create · lore workspace switch · lore audit

Workspace isolation within orgs. Scoped API keys, member management with RBAC roles, and a full audit log of every action (memory.create, key.revoke, etc.).

Plugin SDK

lore plugin create · lore plugin list · lore plugin reload

Extend Lore with plugins discovered via Python entry_points. Five lifecycle hooks (on_remember, on_recall, on_enrich, on_extract, on_score), hot-reload, scaffold CLI, and test harness.

Proactive Recommendations

suggest · lore suggest --context "..." · GET /v1/recommendations

Surface relevant memories before explicit queries. Multi-signal scoring (context similarity, entity overlap, temporal patterns, access patterns) with human-readable explanations and a feedback loop.

Retrieval Analytics

GET /v1/analytics/retrieval · Prometheus metrics

Track hit rate, score distribution, memory utilization, and latency. Know whether memories are actually helping your agents.

Quick Start

Docker Compose (recommended)

git clone https://github.com/agentkitai/lore.git
cd lore
docker compose up -d

Starts Postgres with pgvector and the Lore server on http://localhost:8765.

pip

pip install "lore-sdk[server,solo]"
lore serve  # starts on port 8765

Verify it works

curl http://localhost:8765/v1/memories

Add Lore as an MCP server

One line — no install — drops Lore into any MCP client (Claude Code, Cursor, VS Code, Codex, Claude Desktop):

// Claude Code: .mcp.json  ·  Claude Desktop: claude_desktop_config.json
{
  "mcpServers": {
    "lore": { "command": "uvx", "args": ["--from", "lore-sdk[mcp]", "lore-memory"] }
  }
}

Already installed (pip install lore-sdk[mcp])? Use "command": "lore-memory" (or lore mcp). Per-client guides are in Multi-Agent Setup below; lore integrate --platform <client> writes the config for you.

Multi-Agent Setup

Claude Code

Option A: Auto-retrieval hook (recommended)

lore setup claude-code

This installs a UserPromptSubmit hook that auto-injects relevant memories into every prompt.

Option B: MCP tools

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "lore": {
      "command": "lore",
      "args": ["mcp"],
      "env": {
        "LORE_API_URL": "http://localhost:8765",
        "LORE_API_KEY": "your-api-key"
      }
    }
  }
}

OpenClaw

lore setup openclaw

Installs a message:preprocessed hook for auto-retrieval. Memories appear in context before every agent response.

Cursor

lore setup cursor

Installs a beforeSubmitPrompt hook. Also add MCP config to .cursorrules:

{
  "mcpServers": {
    "lore": {
      "command": "lore",
      "args": ["mcp"],
      "env": {
        "LORE_API_URL": "http://localhost:8765",
        "LORE_API_KEY": "your-api-key"
      }
    }
  }
}

Codex CLI

lore setup codex

Installs a beforePlan hook. Add MCP config:

{
  "mcpServers": {
    "lore": {
      "command": "lore",
      "args": ["mcp"],
      "env": {
        "LORE_API_URL": "http://localhost:8765",
        "LORE_API_KEY": "your-api-key"
      }
    }
  }
}

Any HTTP client

Auto-retrieval works with any system that can make an HTTP call before sending a prompt:

curl -s "http://localhost:8765/v1/retrieve?query=your+prompt&limit=5&min_score=0.3&format=markdown" \
  -H "Authorization: Bearer $LORE_API_KEY"

MCP Tools Reference

Tool	Description
remember	Store a memory with type, tier, tags, metadata
recall	Semantic search with temporal/graph-enhanced retrieval
forget	Delete a memory by ID
list_memories	List memories with filtering
stats	Memory statistics (total, by type/tier)
upvote_memory	Boost memory ranking
downvote_memory	Lower memory ranking
graph_query	Hop-by-hop knowledge graph traversal
entity_map	List entities (optional D3 format)
related	Find related memories/entities
extract_facts	Extract (subject, predicate, object) triples
list_facts	List active facts
conflicts	List detected fact conflicts
classify	Intent, domain, emotion classification
enrich	LLM-powered metadata extraction
consolidate	Merge duplicate/related memories
ingest	Accept content from external sources
github_sync	Sync GitHub repo data
check_freshness	Verify memory freshness against git
as_prompt	Export memories formatted for LLM injection
add_conversation	Extract memories from conversation messages
recent_activity	Recent memory activity summary
topics	List auto-detected recurring topics
topic_detail	Deep dive on a topic (memories, entities, timeline)
export	Export all data to JSON
snapshot	Create data backup
snapshot_list	List available snapshots
save_snapshot	Save session snapshot
review_digest	Get pending connections for review
review_connection	Approve/reject a pending connection
on_this_day	Memories from same date across years
suggest	Proactive memory recommendations based on session context
remember_observation	Record a structured observation from a session
search	Progressive-disclosure compact index (id, title, score)
get_memories	Fetch full payloads for one or more memory IDs
timeline	Chronologically adjacent events around an anchor memory
promote_memory	Share a private memory with the team (private→shared)
demote_memory	Unshare a memory, making it private again
supersede	Mark a memory as superseded by a newer one
list_at_time	List memories that were canonical at a given time
consolidate_memories	Create a merged memory and supersede all sources
provenance	Full lineage for a memory (sources + supersession chain)
supersession_chain	Supersession audit chain for a memory
facts_at_time	Facts about an entity that were valid at a given time
supersede_fact	Supersede a fact with a newer one (never deletes)
fact_supersession_chain	Correction trail for a fact

CLI Reference

# Memory operations
lore remember "API rate limit is 100 req/min" --tags api,limits
lore recall "rate limits" --limit 5
lore forget <memory-id>
lore memories --tier long_term
lore stats

# Knowledge graph
lore graph "authentication" --depth 2
lore entities --limit 50
lore facts "extract facts from this text"
lore conflicts

# Session & context
lore recent --hours 24
lore on-this-day

# Export & backup
lore export --format json > backup.json
lore import backup.json
lore snapshot-save --title "before refactor"

# Server & setup
lore bootstrap               # validate prerequisites
lore serve                    # start HTTP server
lore mcp                     # start MCP server
lore ui                      # start web UI
lore setup claude-code       # install hooks
lore setup claude-code --validate --test-connection

# SLO management
lore slo create --name "P99 < 50ms" --metric p99_latency --threshold 50 --operator lt
lore slo status
lore slo alerts

# Retrieval profiles
lore profiles list
lore profiles create --name fast-coding --semantic-weight 1.0 --recency-bias 7

# Retention policies
lore policy create --name prod --snapshot-schedule "0 2 * * *" --max-snapshots 30
lore policy compliance
lore restore-drill --latest

# Workspaces
lore workspace create dev-team
lore workspace switch dev-team
lore audit --since 24h

# Plugins
lore plugin create my-tagger
lore plugin list
lore plugin reload my-tagger

# Recommendations
lore suggest --context "setting up docker"

# Review (with risk scoring)
lore review list --sort risk
lore review approve <id> --note "Verified"
lore review batch approve --ids id1,id2

# API keys
lore keys create --name "my-agent"
lore keys list
lore keys revoke <key-id>

API Reference

Key endpoints

# Memory CRUD
GET    /v1/retrieve                    # Auto-retrieval (for hooks)
POST   /v1/memories                    # Create memory
POST   /v1/memories/search             # Semantic search
GET    /v1/memories                    # List memories
GET    /v1/memories/{id}               # Get memory
PATCH  /v1/memories/{id}               # Update memory
DELETE /v1/memories/{id}               # Delete memory

# Knowledge graph
GET    /v1/graph                       # Knowledge graph
GET    /v1/graph/topics                # Topic list
GET    /v1/graph/topics/{name}         # Topic detail
GET    /v1/graph/entity/{id}           # Entity detail

# Bi-temporal & supersession (history without deletion)
POST   /v1/memories/{id}/supersede            # Mark superseded (by=null un-supersedes)
GET    /v1/memories/at_time                   # Memories canonical as of ?at=<ts>
GET    /v1/memories/{id}/supersession-chain   # Memory correction audit trail
GET    /v1/memories/{id}/provenance           # Full lineage (sources + chain)
POST   /v1/memories/consolidate               # Merge N memories + supersede sources
GET    /v1/facts/at_time                      # Facts about an entity valid at ?at=<ts>
POST   /v1/facts/{id}/supersede               # Supersede-not-delete a fact edge
GET    /v1/facts/{id}/supersession-chain      # Fact correction trail
GET    /v1/timeline                           # Chronologically adjacent events

# Ingestion
POST   /v1/conversations              # Extract memories from conversation
POST   /v1/ingest                     # Ingest external content

# Review + risk scoring
GET    /v1/review                     # Pending reviews (sortable by risk)
POST   /v1/review/{id}               # Approve/reject with notes
POST   /v1/review/bulk               # Batch approve/reject
GET    /v1/review/history             # Decision audit trail

# Export & snapshots
POST   /v1/export                     # Export all data
POST   /v1/import                     # Import data
POST   /v1/export/snapshots           # Create snapshot
GET    /v1/export/snapshots           # List snapshots

# SLO dashboard
GET    /v1/slo                        # List SLO definitions
POST   /v1/slo                        # Create SLO
GET    /v1/slo/status                 # Current pass/fail per SLO
GET    /v1/slo/alerts                 # Alert history
GET    /v1/slo/timeseries             # Time-series for charts

# Retrieval profiles
GET    /v1/profiles                   # List profiles
POST   /v1/profiles                   # Create profile
GET    /v1/retrieve?profile=coding    # Retrieve with profile

# Retention policies
GET    /v1/policies                   # List policies
POST   /v1/policies                   # Create policy
GET    /v1/policies/compliance        # Compliance summary
POST   /v1/policies/{id}/drill       # Execute restore drill

# Workspaces + RBAC
POST   /v1/workspaces                 # Create workspace
GET    /v1/workspaces                 # List workspaces
POST   /v1/workspaces/{id}/members   # Add member
GET    /v1/audit                      # Query audit log

# Plugins
GET    /v1/plugins                    # List plugins
POST   /v1/plugins/{name}/enable     # Enable plugin
POST   /v1/plugins/{name}/reload     # Hot-reload plugin

# Recommendations
POST   /v1/recommendations           # Get proactive suggestions
POST   /v1/recommendations/{id}/feedback  # Thumbs up/down
PATCH  /v1/recommendations/config    # Adjust aggressiveness

# Setup validation
POST   /v1/setup/validate            # Test connectivity

# Analytics & monitoring
GET    /v1/recent                     # Recent activity
GET    /v1/analytics/retrieval        # Retrieval analytics
GET    /metrics                       # Prometheus metrics

# API keys
POST   /v1/keys                       # Create API key
GET    /v1/keys                       # List API keys
DELETE /v1/keys/{id}                  # Revoke API key

Configuration

Variable	Default	Description
DATABASE_URL	—	PostgreSQL connection string
LORE_PORT	8765	Server port
LORE_API_KEY	—	API key for authentication
LORE_API_URL	http://localhost:8765	Remote server URL
LORE_PROJECT	—	Default project scope
LORE_SNAPSHOT_THRESHOLD	30000	Characters before auto-snapshot
LORE_ENRICHMENT_ENABLED	false	Enable LLM enrichment pipeline
LORE_ENRICHMENT_MODEL	gpt-4o-mini	Model for enrichment
LORE_LLM_PROVIDER	—	LLM provider override
LORE_LLM_API_KEY	—	LLM API key
LORE_LLM_MODEL	—	LLM model override
LORE_LLM_BASE_URL	—	LLM base URL
LORE_GRAPH_DEPTH	2	Default graph traversal depth
LORE_GRAPH_CONFIDENCE_THRESHOLD	0.5	Entity confidence threshold
LORE_GRAPH_EXTRACTION_ENABLED	true	Entity extraction from new memories. On by default — entities come from local spaCy NER (no LLM, no claude CLI), with a proper-noun heuristic fallback when spaCy/en_core_web_sm isn't installed. Set false to disable. Install lore-sdk[ner] + python -m spacy download en_core_web_sm for best entities.
LORE_GRAPH_LLM	false	Use the claude CLI to extract entities and relationships (subject→predicate→object) instead of local entity-only extraction. Needs Claude Code on PATH.
LORE_GRAPH_EXTRACTION_CONCURRENCY	2	Max concurrent claude extraction subprocesses (LLM path only)
LORE_GRAPH_EXTRACTION_TIMEOUT	30	Per-extraction subprocess timeout, seconds (LLM path only)
LORE_CONTRADICTION_DETECTION	auto	Write-time contradiction detection + soft-supersession. Auto-on when OPENAI_API_KEY is set (it's LLM-scored); set true/false to override. Flags the new memory and soft-supersedes the older contradicted one (recall suppresses superseded memories ×0.1 — not deleted).
LORE_CONTRADICTION_SUPERSEDE	true	Soft-supersede the older contradicted memory (last-write-wins). false = flag-only (old behavior). Only your own / unowned memories are superseded; cross-agent conflicts are flag-only.
LORE_CONTRADICTION_SUPERSEDE_MIN_CONFIDENCE	0.75	Confidence bar to supersede (higher than the flag bar, LORE_CONTRADICTION_MIN_CONFIDENCE=0.6).
LORE_AUTO_SAVE	true	Auto-capture (Claude Code hooks) master switch; false disables all capture.
LORE_CAPTURE_N	0	Auto-capture mid-session batch size. 0 = buffer-only (extract per-turn at Stop); >0 spawns capture-extract every N tool calls (the old default was 10).
LORE_EXTRACT_ON_STOP	true	Auto-capture: extract once per completed agent turn (Stop hook). false = strict end-of-session-only extraction.
LORE_HTTP_TIMEOUT	30	HTTP timeout (seconds)
OPENAI_API_KEY	—	Auto-enables enrichment when set
SLO_CHECK_INTERVAL	60	SLO evaluation interval (seconds)
ALERT_WEBHOOK_URL	—	Default webhook URL for SLO alerts
SMTP_HOST	—	SMTP server for email alerts
SMTP_PORT	587	SMTP port
SMTP_USER	—	SMTP username
SMTP_FROM	—	Email sender address
AUTH_MODE	api-key-only	Auth mode: api-key-only, dual, oidc-required
LORE_WORKSPACE	—	Default workspace slug

Architecture

┌──────────────────────────────────────────────────────────────┐
│                      Agent Runtimes                          │
│  Claude Code · OpenClaw · Cursor · Codex · Any HTTP client   │
└──────────┬──────────────────────────────────┬────────────────┘
           │ hooks (auto-retrieval)           │ MCP tools
           ▼                                  ▼
┌──────────────────────────────────────────────────────────────┐
│                     Lore Server (:8765)                       │
│                                                              │
│  REST API · MCP Server · Web UI (/ui/) · Plugin SDK          │
│                                                              │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────┐ │
│  │  Embedder   │  │  Knowledge   │  │  LLM Pipeline       │ │
│  │  (ONNX)     │  │  Graph       │  │  (optional)         │ │
│  │  pgvector   │  │  + Review    │  │  classify · enrich   │ │
│  │  + Profiles │  │  + Risk      │  │  extract · recommend │ │
│  └─────────────┘  └──────────────┘  └─────────────────────┘ │
│                                                              │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────┐ │
│  │  SLO        │  │  Retention   │  │  Workspaces         │ │
│  │  Checker    │  │  Scheduler   │  │  + RBAC             │ │
│  │  + Alerting │  │  + Drills    │  │  + Audit Log        │ │
│  └─────────────┘  └──────────────┘  └─────────────────────┘ │
└──────────────────────────┬───────────────────────────────────┘
                           │
              ┌────────────▼────────────┐
              │   PostgreSQL + pgvector  │
              │   memories · entities    │
              │   relationships · facts  │
              │   slo · profiles · audit │
              │   workspaces · policies  │
              └─────────────────────────┘

Performance

Operation	Latency
/v1/retrieve (warm)	~20ms
remember() (no LLM)	< 100ms
recall() 100 memories	< 50ms
recall() 10K memories	< 200ms
recall() graph-enhanced	< 500ms
Embedding (500 words)	< 200ms

Contributing

git clone https://github.com/agentkitai/lore.git
cd lore
pip install -e ".[dev,server,mcp,enrichment]"
docker compose up -d db  # Postgres + pgvector
pytest

License

MIT