Metadata-Version: 2.4
Name: lore-sdk
Version: 1.1.1
Summary: Cross-agent semantic memory with knowledge graphs, fact extraction, and MCP integration
Project-URL: Homepage, https://github.com/amitpaz1/lore
Project-URL: Repository, https://github.com/amitpaz1/lore
Project-URL: Documentation, https://github.com/amitpaz1/lore/tree/main/docs
Project-URL: Issues, https://github.com/amitpaz1/lore/issues
Project-URL: Changelog, https://github.com/amitpaz1/lore/blob/main/CHANGELOG.md
Author-email: Amit Paz <amit.paz@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,agent-memory,ai-memory,cognitive-memory,fact-extraction,knowledge,knowledge-graph,lore,mcp,memory,memory-consolidation,model-context-protocol,semantic-memory
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: numpy>=1.21.0
Requires-Dist: onnxruntime>=1.14.0
Requires-Dist: python-ulid>=2.0.0
Requires-Dist: tokenizers>=0.13.0
Provides-Extra: aws
Requires-Dist: boto3>=1.26.0; extra == 'aws'
Provides-Extra: dev
Requires-Dist: httpx>=0.24.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: enrichment
Requires-Dist: litellm>=1.0; extra == 'enrichment'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Provides-Extra: ner
Requires-Dist: spacy>=3.5.0; extra == 'ner'
Provides-Extra: redis
Requires-Dist: redis>=4.5.0; extra == 'redis'
Provides-Extra: remote
Requires-Dist: httpx>=0.24.0; extra == 'remote'
Provides-Extra: security
Requires-Dist: detect-secrets>=1.4.0; extra == 'security'
Provides-Extra: server
Requires-Dist: asyncpg>=0.28.0; extra == 'server'
Requires-Dist: fastapi>=0.100.0; extra == 'server'
Requires-Dist: pydantic>=2.0.0; extra == 'server'
Requires-Dist: pyjwt[crypto]>=2.8; extra == 'server'
Requires-Dist: uvicorn>=0.22.0; extra == 'server'
Description-Content-Type: text/markdown

# 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)
[![Docker](https://img.shields.io/docker/v/agentkitai/lore?label=docker)](https://hub.docker.com/r/agentkitai/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)

**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, importance scoring, 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.

### 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]
lore serve  # starts on port 8765
```

### Verify it works

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

## 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, importance) |
| `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 |

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

# 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_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
