Lore
Cross-agent memory over MCP: hybrid recall, knowledge graph, private/shared visibility, redaction.
Open source Open in the app JSON README (API)
About
Cross-agent memory over MCP: hybrid recall, knowledge graph, private/shared visibility, redaction.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- agentkitai
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.4.2
- Stars
- 8
- Open pull requests
- 11
- Last push
- 2026-09-06T01:24:03Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:23
- Updated
- 2026-08-29 03:02:23
- Origin id
io.github.agentkitai/lore
README
# Lore — Universal AI Memory Layer
[](https://pypi.org/project/lore-sdk/)
[](https://www.npmjs.com/package/lore-sdk)
[](https://github.com/agentkitai/lore/pkgs/container/lore)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](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