# Lore — Universal AI Memory Layer

[![PyPI](https://img.shields.io/pypi/v/lore-sdk)](https://pypi.org/project/lore-sdk/)
[![npm](https://img.shields.io/npm/v/lore-sdk)](https://www.npmjs.com/package/lore-sdk)
[![Container](https://img.shields.io/badge/ghcr.io-agentkitai%2Flore-2496ED?logo=docker&logoColor=white)](https://github.com/agentkitai/lore/pkgs/container/lore)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/github/license/agentkitai/lore)](LICENSE)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)
[![Tests](https://img.shields.io/github/actions/workflow/status/agentkitai/lore/ci.yml?label=tests)](https://github.com/agentkitai/lore/actions)

<!-- mcp-name: io.github.agentkitai/lore -->

**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)

```bash
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

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

### Verify it works

```bash
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):

```jsonc
// 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](#multi-agent-setup) below; `lore integrate --platform <client>` writes the config for you.

## Multi-Agent Setup

### Claude Code

**Option A: Auto-retrieval hook (recommended)**

```bash
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`:

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

### OpenClaw

```bash
lore setup openclaw
```

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

### Cursor

```bash
lore setup cursor
```

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

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

### Codex CLI

```bash
lore setup codex
```

Installs a `beforePlan` hook. Add MCP config:

```json
{
  "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:

```bash
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

```bash
# 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

```bash
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