Lore Context

<div align="center">

Lore Context

The control plane for AI-agent memory, eval, and governance.

Know what every agent remembered, used, and should forget — before memory becomes production risk.

    

Getting Started · Website Quickstart · Benchmark Methodology · API Reference · Architecture · Project Plan · Release Status · Roadmap · Integrations · Deployment · Changelog

🌐 Read this in your language: English · 简体中文 · 繁體中文 · 日本語 · 한국어 · Tiếng Việt · Español · Português · Русский · Türkçe · Deutsch · Français · Italiano · Ελληνικά · Polski · Українська · Bahasa Indonesia

Localized docs may lag the current English release notes; the canonical v2.1 docs are the English README and docs/ set.

</div>

---

What is Lore Context

Lore Context is an open-core control plane for AI-agent memory: it composes context across memory, search, repository graphs, and tool traces; evaluates retrieval quality on your own datasets; routes governance review for sensitive content; and exports memory as a portable interchange format you can move between backends.

It does not try to be another memory database. The unique value is what sits on top of memory:

• Context Query — single endpoint composes memory + web + repo + tool traces, returns a graded context block with provenance.
• Memory Eval — runs Recall@K, Precision@K, MRR, stale-hit-rate, p95 latency on datasets you own; persists runs and diffs them for regression detection.
• Governance Review — six-state lifecycle (candidate / active / flagged / redacted / superseded / deleted), risk-tag scanning, poisoning heuristics, immutable audit log.
• MIF-like Portability — JSON + Markdown export/import preserving provenance / validity / confidence / source_refs / supersedes / contradicts. Works as a migration format between memory backends.
• Repo Graph — deterministic repository indexing (files, symbols, imports, calls, routes, tests) exposed as API routes and read-only MCP tools so agents ground repository answers in a stable project-context contract.
• Multi-Agent Adapter — first-class agentmemory integration with version probe + degraded-mode fallback; clean adapter contract for additional runtimes.

When to use it

| Use Lore Context when... | Use a memory database (agentmemory, Mem0, Supermemory) when... | |---|---| | You need to prove what your agent remembered, why, and whether it was used | You just need raw memory storage | | You run multiple agents (Claude Code, Cursor, Qwen, Hermes, Dify) and want shared trustable context | You're building a single agent and OK with a vendor-locked memory tier | | You require local or private deployment for compliance | You prefer a hosted SaaS | | You need eval on your own datasets, not vendor benchmarks | Vendor benchmarks are sufficient signal | | You want to migrate memory between systems | You don't plan to ever switch backends |

Quick Start

# 1. Clone + install
git clone https://github.com/Lore-Context/lore-context.git
cd lore-context && pnpm install

# 2. Run the quickstart helper and inspect the activation report
pnpm quickstart -- --dry-run --activation-report

# 3. Generate a real API key (do not use placeholders in any environment beyond local-only dev)
export LORE_API_KEY=$(openssl rand -hex 32)

# 4. Start the API (file-backed, no Postgres required)
pnpm build && PORT=3000 LORE_STORE_PATH=./data/lore-store.json pnpm start:api

# 5. Write a memory
curl -H "Authorization: Bearer $LORE_API_KEY" -H "Content-Type: application/json" \
  -X POST http://127.0.0.1:3000/v1/memory/write \
  -d '{"content":"Use RDS as truth store and Qdrant as the derived recall index for Lore Context production.","memory_type":"project_rule","project_id":"demo"}'

# 6. Query context, then inspect the returned traceId in the Evidence Ledger
curl -H "Authorization: Bearer $LORE_API_KEY" -H "Content-Type: application/json" \
  -X POST http://127.0.0.1:3000/v1/context/query \
  -d '{"query":"production storage","project_id":"demo","token_budget":1200}'

For the public website quickstart, see lorecontext.com/quickstart. For full setup (Postgres, Docker Compose, Dashboard, MCP integration), see docs/getting-started.md.

The canonical alpha quickstart is git clone + pnpm quickstart. Lore does not currently publish or claim a public @lore-context/quickstart npm package. The MCP stdio server is published separately as @lore-context/server for registry and client distribution, and the SDK middleware ships as @lore-context/sdk-middleware (npm) and lore-context-middleware (PyPI).

For AI-readable discovery, the website publishes /llms.txt and /llms-full.txt from public documentation only. The Official MCP Registry entry is published, and additional distribution drafts live under docs/distribution. Launch drafts live under docs/launch, and design partner intake under docs/design-partners. The public benchmark page is a reproducible methodology and small smoke-run report, not a competitive benchmark-win claim.

Architecture

The diagram below shows the full open-core plus hosted-production shape. In the public OSS repo, local file/Postgres deployment is supported directly; hosted Google sign-in, AWS SQS workers, private embeddings, billing, and multi-tenant operations are commercial hosted-cloud surfaces.

                       ┌───────────────────────────────────────────────┐
  MCP/REST clients ─► │ apps/api  (auth + rate limit + evidence)       │
  (Claude Code,       │   ├── Memory Inbox / lifecycle / audit         │
   Codex, Cursor,     │   ├── capture ingestion + recall hydration     │
   OpenCode...)       │   ├── context query (memory/web/repo/traces)   │
                       │   ├── repo graph query / symbol / impact       │
                       │   ├── Google sign-in + hosted MCP metadata     │
                       │   └── OpenAPI + usage + operator surfaces      │
                       └───────────────┬───────────────────────────────┘
                                       │
                         capture / embedding / graph jobs
                                       ▼
                       ┌───────────────────────────────────────────────┐
                       │ memory-worker  (AWS SQS + DLQ fan-out)        │
                       │   ├── auto redaction / curation / save        │
                       │   ├── dreaming butler (prune/merge/resolve)    │
                       │   ├── private Qwen3 embedding service         │
                       │   └── Qdrant dense+sparse indexing            │
                       └───────────────┬───────────────────────────────┘
                                       │
                  ┌────────────────────┼────────────────────┐
                  ▼                    ▼                    ▼
          RDS PostgreSQL 16      Qdrant derived index   apps/dashboard
          truth store + audit    lore_memories_v12      user-facing SaaS

For detail, see docs/architecture.md.

What's in v2.1.0

v2.1.0 is the Repo Graph API and MCP Tools release. It makes Lore's own repository graph a first-class agent memory surface: deterministic TypeScript/JavaScript repository indexing for files, symbols, imports, calls, routes, tests, and process hints, exposed through API routes and read-only MCP tools so agents ground repository answers in a stable project-context contract instead of ad hoc text search.

v2.1.0 is the current open-core source line. The hosted Lore Cloud production line also runs v2.1.0 on the commercial AWS/Qdrant/private-embedding substrate, but hosted operations, billing, production release automation, and Secret Vault runtime stay in Lore-Context/lore-cloud.

| Capability | Status | Where | |---|---|---| | Repo graph API + MCP tools (repo.graph_query / symbol_context / impact / detect_changes) | ✅ OSS + hosted production | packages/repo-graph, apps/api, apps/mcp-server | | Code knowledge graph indexer | ✅ OSS + hosted production | packages/code-indexer, packages/code-indexer-python | | Context Query composing memory + web + repo + tool traces | ✅ OSS + hosted production | apps/api, docs/api-reference.md | | 7-stream HybridSearchOrchestrator (FTS / pgvector / Qdrant dense+sparse / graph / temporal / wiki) | ✅ OSS + hosted production | packages/search | | Cross-encoder reranker (post-fusion, opt-in) | ✅ OSS, provider key required | apps/api/src/rerankers/ | | Dreaming butler memory consolidation (prune / merge / resolve / surface) | ✅ OSS, flag-gated | apps/api/src/workers/butler-v18.ts | | Agent memory self-improvement loop + context recipes | ✅ OSS, human-gated promotion | packages/eval, packages/search | | SDK middleware (auto-inject + auto-retain for OpenAI / Anthropic clients) | ✅ Published | packages/sdk-middleware-typescript, packages/sdk-middleware-python | | Generated SDK source previews | ✅ OSS source preview | packages/sdk-python, packages/sdk-go, packages/sdk-java, packages/sdk-dotnet | | Browser extension capture scaffold | ✅ OSS scaffold | apps/browser-extension | | Secret vault for AI agents (MCP-native, three-button authorization) | Hosted beta, pending crypto audit | commercial runtime in Lore-Context/lore-cloud | | Cloud Memory Engine: RDS truth store + SQS worker fan-out + Qdrant index | Hosted production | commercial hosted cloud | | Private Qwen3-Embedding-0.6B 1024-dim vector service | Hosted production | commercial hosted cloud | | Automatic capture ingestion and Memory Inbox exceptions | ✅ OSS + hosted production | apps/api, packages/capture, apps/dashboard | | Google sign-in + personal vault bootstrap | Hosted production | commercial hosted cloud | | Commercial SaaS: individual subscriptions, billing, quota gating | Hosted production | Lore-Context/lore-cloud | | REST API with API-key auth (reader/writer/admin) | ✅ OSS + hosted production | apps/api | | OpenAPI 3.1 contract at /openapi.json (reports 2.1.0) | ✅ OSS + hosted production | apps/api/src/openapi.ts | | MCP stdio server (legacy + official SDK transport) | ✅ OSS + hosted production | apps/mcp-server | | Next.js dashboard customer workflow scaffold | ✅ OSS scaffold + hosted production | apps/dashboard | | Evidence Ledger API + Dashboard summary | ✅ OSS + hosted production | apps/api, apps/dashboard | | Governance state machine + audit log | ✅ OSS + hosted production | packages/governance | | Eval runner (Recall@K / Precision@K / MRR / staleHit / p95) | ✅ OSS + hosted production | packages/eval | | MIF v0.2 import/export with supersedes + contradicts | ✅ OSS | packages/mif | | Model gateway (multi-provider task→model routing) | ✅ OSS | packages/model-gateway | | agentmemory adapter with version probe + degraded mode | ✅ OSS | packages/agentmemory-adapter | | Rate limiting, structured JSON logging with field redaction | ✅ OSS + hosted production | apps/api | | Docker Compose private deployment | ✅ OSS self-host | docker-compose.yml, docs/deployment/ | | pnpm quickstart local adoption helper + activation report | ✅ OSS | scripts/lore-quickstart.mjs | | Official MCP Registry + distribution / launch / design-partner docs | ✅ OSS docs | server.json, docs/distribution/, docs/launch/ |

See CHANGELOG.md for the full release history.

Current release status

v2.1.0 is the current source, hosted production, and release line. It deployed to AWS production and the public website through the optimized release flow: immutable arm64-first artifacts, staging API smoke, production API deploy, isolated website deploy, post-release audit, and tag/release closure. External checks confirm https://api.lorecontext.com/health returns status=ok, /openapi.json reports 2.1.0, and https://lorecontext.com/status.html contains v2.1.0.

Production keeps the v1.1+ RDS / SQS / memory-worker / Qdrant cloud shape, uses lore_memories_v12 as the Qdrant collection, keeps 1024-dim pgvector for the Postgres path, and adds the additive repo graph schema (apps/api/src/db/schema-v21-repo-graph.sql).

See docs/release-status.md for the current public-safe status snapshot and docs/release-notes/v2.1.0.md for the full release notes.

Release focus

The v2.1 release makes Lore's repository graph a first-class agent memory surface. The goal is to let agents answer "where is X defined", "what calls this", and "what breaks if I change this" against a deterministic, stable project-context contract rather than ad hoc text search:

• @lore/repo-graph — deterministic TypeScript/JavaScript repository indexing

for files, symbols, imports, calls, routes, tests, and process hints.

• API routes: POST /v1/repo/graph/query, POST /v1/repo/symbol/context,

POST /v1/repo/impact, and POST /v1/repo/detect-changes.

• MCP tools: repo.graph_query, repo.symbol_context, repo.impact, and

repo.detect_changes (read-only).

• context_query(repo) now uses provider-backed repo graph evidence when

available, with an honest unavailable fallback when repo graph storage is not configured.

• The repo graph Postgres schema is additive — it sits on top of the existing

production schema and is applied during production/staging schema setup.

Root and API package versions report 2.1.0 so /openapi.json matches the release tag. The release train uses the optimized split API/website deployment guardrails introduced after v2.0.9.

See docs/project-plan.md, docs/roadmap.md, and docs/release-governance.md.

Integrations

Lore Context speaks MCP and REST and integrates with most agent IDEs and chat frontends:

| Tool | Setup guide | |---|---| | Claude Code | docs/integrations/claude-code.md | | Cursor | docs/integrations/cursor.md | | Qwen Code | docs/integrations/qwen-code.md | | OpenClaw | docs/integrations/openclaw.md | | Hermes | docs/integrations/hermes.md | | Dify | docs/integrations/dify.md | | FastGPT | docs/integrations/fastgpt.md | | Cherry Studio | docs/integrations/cherry-studio.md | | Roo Code | docs/integrations/roo-code.md | | OpenWebUI | docs/integrations/openwebui.md | | Other / generic MCP | docs/integrations/README.md |

Deployment

| Mode | Use when | Doc | |---|---|---| | Local file-backed | Solo dev, prototype, smoke testing | This README, Quick Start above | | Local Postgres+pgvector | Single-node local fallback and migration testing | docs/deployment/README.md | | Docker Compose private | Self-hosted team deployment, isolated network | docs/deployment/compose.private-demo.yml | | Hosted cloud | RDS / SQS / memory-worker / Qdrant / private embedding plus the graph-augmented hybrid recall stack and commercial SaaS substrate | docs/release-status.md |

All deployment paths require explicit secrets. Local/private paths require POSTGRES_PASSWORD, LORE_API_KEYS, and dashboard auth. Hosted deployments also need RDS, SQS, Qdrant, embedding-service, OAuth, tunnel configuration, and the production runtime exports. The scripts/check-env.mjs script refuses production startup if any value matches a placeholder pattern.

Security

v2.1.0 keeps the local/private deployment posture and the hosted cloud guardrails for ordinary-user access:

• Authentication: API-key bearer tokens with role separation (reader/writer/admin) and per-project scoping. Empty-keys mode fails closed in production.
• Rate limiting: per-IP + per-key dual bucket with auth-failure backoff (429 after 5 fails in 60s, 30s lockout).
• Dashboard: Google session flow for the hosted product; HTTP Basic Auth remains available for local/private operator deployments.
• Containers: all Dockerfiles run as non-root node user; HEALTHCHECK on api + dashboard.
• Secrets: zero hardcoded credentials; all defaults are required-or-fail variables. scripts/check-env.mjs rejects placeholder values in production.
• Governance: PII / API key / JWT / private-key regex scanning on writes; risk-tagged content auto-routed to review queue; immutable audit log on every state transition.
• Memory poisoning: heuristic detection on consensus + imperative-verb patterns.
• MCP: zod schema validation on every tool input; mutating tools require reason (≥8 chars) and surface destructiveHint: true; upstream errors sanitized before client return.
• Worker isolation: capture, embedding, graph, connector, and backfill jobs run through AWS SQS queues with DLQs; Qdrant is a derived index and RDS remains authoritative.
• Logging: structured JSON with auto-redaction of content, query, memory, value, password, secret, token, key fields.

Vulnerability disclosures: SECURITY.md.

Project structure

apps/
  api/                # REST control plane + Postgres + governance + eval + repo graph
  dashboard/          # Next.js dashboard scaffold; hosted Google session stays commercial
  mcp-server/         # MCP stdio server (legacy + official SDK transports)
  cli/                # lore CLI (doctor, wiki-recompile, dataset import/export)
  browser-extension/  # Capture surface scaffold
  web/                # Server-side HTML renderer (no-JS fallback UI)
  website/            # Marketing site (handled separately)
packages/
  shared/             # Shared types, errors, ID/token utilities
  agentmemory-adapter # Bridge to upstream agentmemory + version probe
  search/             # 7-stream HybridSearchOrchestrator + recipe adapter
  repo-graph/         # Deterministic repository indexing (v2.1)
  code-indexer/       # Code knowledge graph indexer (TypeScript/JavaScript)
  code-indexer-python # Code knowledge graph indexer (Python)
  capture/            # Capture ingestion primitives
  connectors/         # External source connectors
  model-gateway/      # Multi-provider task→model routing
  mif/                # Memory Interchange Format (v0.2)
  eval/               # EvalRunner + metric primitives + context recipes
  governance/         # State machine + risk scan + poisoning + audit
  profile/            # Vault / account profile types
  sdk-typescript/     # TypeScript client SDK
  sdk-python/         # Python client SDK
  sdk-go/ sdk-java/ sdk-dotnet/   # Additional language SDKs
  sdk-middleware-typescript/      # Auto-inject + auto-retain middleware (npm)
  sdk-middleware-python/          # Auto-inject + auto-retain middleware (PyPI)
docs/
  i18n/<lang>/        # Localized README in 17 languages
  integrations/       # Agent-IDE integration guides
  deployment/         # Local and Docker Compose private deployment docs
  legal/              # Privacy / Terms / Cookies (Singapore law)
scripts/
  check-env.mjs       # Production-mode env validation
  smoke-*.mjs         # End-to-end smoke tests
  apply-postgres-schema.mjs

Requirements

• Node.js >=22
• pnpm 10.30.1
• (Optional local fallback) Postgres 16 with pgvector
• (Hosted/advanced) RDS PostgreSQL 16, AWS SQS, Qdrant, and private embedding service

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for the development workflow, commit message protocol, and review expectations.

For documentation translations, see the i18n contributor guide.

Operated by

Lore Context is operated by REDLAND PTE. LTD. (Singapore, UEN 202304648K). Company profile, legal terms, and data handling are documented under docs/legal/.

License

The Lore Context repository is licensed under Apache License 2.0. Individual packages under packages/* declare MIT to enable downstream consumption. See NOTICE for upstream attribution.

Acknowledgments

Lore Context builds on top of agentmemory as a local memory runtime. Upstream contract details and version-compatibility policy are documented in UPSTREAM.md.