openmemory

# OpenMemory OpenMemory is open-source memory infrastructure for AI tools and MCP clients. It gives each user a portable, graph-aware memory layer that can be shared across assistants, agents, apps, and chat surfaces. The project is intentionally Cloudflare-native: Workers for the API, Durable Objects with SQLite for per-user graph state, D1 for auth/control-plane data, Vectorize and Workers AI for semantic recall, R2 for exports, and Cloudflare's MCP runtime for tool access. > Status: alpha. The core memory API, graph store, OAuth-backed MCP endpoint, > recall flow, source and conversation ingestion, async ingestion jobs, exports, restore, repair > path, dashboard, extraction workers, and local integration suite are working. The > hosted profile/onboarding UI, named MCP request-profile smoke, browser > OAuth callback verification, larger recall benchmarks, typed relationship > diagnostics, production telemetry, and release validation gates are working. > Manual vendor-surface MCP dogfooding for MCP Inspector, Cursor, Claude, and > ChatGPT plus hosted GitHub/Google social OAuth dogfooding are tracked as > strict release gates. Graph/RAG production trend review is also tracked as a > strict launch gate before broader hosted positioning. ## Why OpenMemory AI memory should not be trapped inside one closed chat product. OpenMemory aims to provide the infrastructure layer behind a more portable experience: - Store facts, preferences, decisions, profile details, source chunks, and evolving context in a user-owned memory graph. - Ingest AI chat transcripts as role-preserving conversation chunks with durable `conversationId` provenance. - Recall useful context through keyword, graph, and semantic retrieval. - Let MCP-compatible tools read and write memory through OAuth-backed identity. - Keep the operational footprint small by using Cloudflare services end to end. - Make the implementation inspectable, testable, and self-hostable. ## What Works Today - Multi-user memory isolation through Durable Object names. - SQLite-backed memory graph per tenant with nodes, edges, entities, metadata, tags, confidence, importance, currentness, validity windows, and supersession. - Canonical typed graph relationship taxonomy shared by the API, Durable Object graph store, Eden client, stats, tests, and web explorer. - Memory create, read, update, soft-forget, search, profile, context, graph neighbors, graph stats, source ingestion, conversation transcript ingestion, R2 export, graph restore, and Vectorize repair APIs. - Chunked source/document ingestion with source and chunk provenance. - Async source and conversation ingestion jobs backed by Cloudflare Queues, Workflows, and the tenant Durable Object job ledger. - Async entity and relationship extraction workers that enrich memory metadata and add relationship-specific graph edges. - Deterministic recall reranking that combines retrieval score, reason, confidence, importance, recency, and currentness. - Optional semantic candidate retrieval through Workers AI embeddings and Cloudflare Vectorize. - Optional Workers AI reranking for API and MCP recall when `OPENMEMORY_RERANK_MODEL` is configured. - Semantic index diagnostics that report expected current vectors, stale vector candidates, sampled missing vectors, sampled stale vectors, and repair recommendations. - Better Auth routes, OAuth 2.1/OIDC discovery, dynamic client registration, dashboard-managed public PKCE MCP clients, JWT/JWKS-backed resource tokens, and optional GitHub/Google login providers. - Session-backed workspace and team member management backed by Drizzle/D1. - Confirmed account and tenant deletion paths for graph purge, Vectorize cleanup, R2 export cleanup, and user-owned auth/workspace/OAuth control-plane rows. - Streamable HTTP MCP endpoint with `remember`, `recall`, `profile`, and `forget` tools. - Authenticated OAuth/MCP client registration management, connection listing, and grant revocation. - Worker-hosted TanStack dashboard for capture, recall, forgetting, and local inspection. - TanStack Start web app with a polished hosted-dashboard direction, shared shadcn-style UI package, hosted profile editing, onboarding empty states, memory health metrics, charts, graph operations signals, and an Obsidian-style knowledge map backed by `react-force-graph-2d`. - Wrangler-backed integration tests and optional Docker reproduction. ## Architecture ```txt apps/web TanStack Start app and hosted product UI assets apps/api Cloudflare Worker API, Better Auth, MCP endpoint packages/client Eden Treaty client for typed API access packages/core Shared memory, graph, recall, and auth domain logic packages/ui shadcn-style shared UI primitives ``` Runtime services: - **Cloudflare Workers + Elysia**: HTTP API, auth routes, and MCP transport. - **Cloudflare Worker Assets**: hosted TanStack dashboard shell served from the same Worker origin as the API. - **Durable Objects + SQLite**: isolated per-user memory graph databases. - **Durable Objects**: global application rate limiting. - **D1 + Drizzle**: Better Auth and control-plane schema. - **Vectorize + Workers AI**: embedding generation and semantic retrieval. - **R2**: tenant graph exports and backup artifacts. - **Workers Analytics Engine**: request, error, rate-limit, and async worker telemetry. - **Cloudflare Agents MCP**: streamable HTTP MCP surface. - **Queues + Workflows**: async source ingestion plus memory entity/relationship extraction. The default deployment shape is intentionally monolithic: API routes, Better Auth, hosted TanStack dashboard assets, and `/mcp` ship as one Worker. The build renders `apps/web/dist/client/index.html` from the TanStack server bundle, then Worker Assets serves it while API/auth/MCP paths remain Worker-first. MCP uses Cloudflare Agents' `createMcpHandler`; split it into a dedicated `McpAgent` Worker only if session-specific MCP state or separate operational scaling becomes necessary. Cloudflare AI Search is tracked as an optional managed-search layer, not the core graph/RAG substrate. ## Quick Start Requirements: - Bun `>=1.3.14` - Node-compatible shell tooling - Wrangler auth for Cloudflare resource provisioning or deploys - Docker only if you want the clean container integration runner Install and run local development: ```sh bun install bun run dev:api bun run dev:web ``` Set up Cloudflare resources in a fresh account: ```sh bun run setup:cloudflare ``` The setup script also applies the R2 lifecycle policy. Re-apply or verify it after bucket changes with: ```sh bun run setup:r2-lifecycle ``` Database helpers: ```sh bun run db:generate bun run db:migrate:local bun run db:migrate:remote ``` Current deployed API: ```txt https://openmemory-api.abbierman101.workers.dev ``` Deployment details live in [docs/deployment.md](docs/deployment.md). ## API Surface Useful endpoints: - `GET /` - `GET /health` - `POST /v1/memories` - `GET /v1/memories/:id` - `PATCH /v1/memories/:id` - `DELETE /v1/memories/:id` - `POST /v1/search` - `POST /v1/context` - `POST /v1/ingest` - `POST /v1/sources` - `POST /v1/sources/async` - `POST /v1/conversations` - `POST /v1/conversations/async` - `GET /v1/sources/:sourceId` - `GET /v1/profile` - `GET /v1/readiness` - `GET /v1/account` - `DELETE /v1/account` - `GET /v1/graph/stats` - `GET /v1/graph/relationships` - `GET /v1/graph/:id/neighbors` - `POST /v1/exports` - `POST /v1/imports/preview` with `mode: "replace"` or `mode: "merge"` and optional `conflictPolicy: "skip" | "overwrite"` - `POST /v1/imports` with `mode: "replace"` or `mode: "merge"` and optional `conflictPolicy: "skip" | "overwrite"` - `POST /v1/index/repair` - `DELETE /v1/tenant` - `GET /v1/oauth/connections` - `DELETE /v1/oauth/connections/:clientId` - `POST /mcp` - `GET /.well-known/oauth-authorization-server` - `GET /.well-known/openid-configuration` - `/api/auth/*` During local development, pass `x-openmemory-user-id: local-user`. If `OPENMEMORY_API_TOKEN` is configured, also pass `Authorization: Bearer <token>`. Production rejects tenant headers by design and uses OAuth-backed identity. Every response includes `x-openmemory-request-id` and rate-limit headers for supportability. Configure the per-isolate safety valve with `OPENMEMORY_RATE_LIMIT_PER_MINUTE` or disable it with `OPENMEMORY_RATE_LIMIT_ENABLED=false` for controlled environments. Set `OPENMEMORY_RERANK_MODEL` to opt into a bounded Workers AI rerank pass over recall candidates; leave it unset for deterministic-only recall. ## MCP OpenMemory exposes a streamable HTTP MCP endpoint at: ```txt https://openmemory-api.abbierman101.workers.dev/mcp ``` Requests should include: ```txt Accept: application/json, text/event-stream Content-Type: application/json ``` See [docs/mcp.md](docs/mcp.md) and [docs/mcp-compatibility.md](docs/mcp-compatibility.md) for OAuth discovery, generic client configuration, tested client request shapes, local development, tools, and connection revocation. Real vendor-surface dogfooding for MCP Inspector, Cursor, Claude, and ChatGPT is tracked in [`config/mcp-vendor-dogfood.json`](config/mcp-vendor-dogfood.json). Normal CI validates the status artifact with `bun run mcp:vendor-dogfood:status`; the strict launch gate is `bun run mcp:vendor-dogfood:check` and is expected to fail until all required vendor entries include real evidence. ## Auth The Worker serves Better Auth at `/api/auth/*` and exposes OAuth/OIDC discovery from root well-known URLs. Production MCP and API access use OAuth bearer tokens; verified token subjects become memory tenants. Optional provider secrets enable social login: ```sh bun --cwd apps/api wrangler secret put GITHUB_CLIENT_ID bun --cwd apps/api wrangler secret put GITHUB_CLIENT_SECRET bun --cwd apps/api wrangler secret put GOOGLE_CLIENT_ID bun --cwd apps/api wrangler secret put GOOGLE_CLIENT_SECRET ``` Hosted GitHub and Google social sign-in evidence is tracked in [`config/social-oauth-dogfood.json`](config/social-oauth-dogfood.json). Normal CI validates the status artifact with `bun run social-oauth:status`; the strict launch gate is `bun run social-oauth:check` and is expected to fail until both providers include hosted readiness and sign-in evidence. Auth storage uses `AUTH_DB` D1 through Drizzle when configured and falls back to an in-memory adapter for local tests and development. Note: `kysely@0.28.17` remains installed only as a Better Auth bundling compatibility dependency. OpenMemory's ORM path is Drizzle. ## Testing OpenMemory follows the testing trophy: targeted unit coverage, heavier integration coverage around runtime boundaries, MemoryBench-style recall and graph-scale benchmarks, named MCP client request-profile smoke, and end-to-end browser/API smoke for the deployed product. ```sh bun run release:validate ``` Maintainers can also run the manual `Release Qualification` GitHub Actions workflow before publishing a tag. It records the full local release gate and a configurable high-volume graph scale run, then uploads benchmark JSONL reports as a `benchmark-reports` artifact. Before calling a hosted release broadly production-ready, update the MCP vendor dogfood ledger with real MCP Inspector, Cursor, Claude, and ChatGPT evidence and run the manual `MCP Vendor Dogfood` GitHub Actions workflow in strict mode. Do the same for hosted GitHub and Google sign-in evidence with the manual `Social OAuth Dogfood` workflow. Review graph/RAG production evidence in [`config/rag-production-review.json`](config/rag-production-review.json), then run the strict `RAG Production Review` workflow for hosted graph benchmark trend, semantic RAG trace review, and rerank threshold review. For the faster pull-request loop: ```sh bun run check bun run build bun run test:integration:local bun run test:mcp:sdk bun run test:e2e:local bun run test:benchmark:local ``` The local integration suite starts real Wrangler Workers on randomized non-default ports, applies D1 migrations into isolated local persistence, and exercises Durable Objects, D1 auth storage, Better Auth sessions, OAuth metadata, MCP, graph edges, recall, sync and async source ingestion, extraction workers, Queues, Workflows, exports, index repair, and the dashboard API. The MCP SDK smoke starts local Wrangler and drives `/mcp` through the official TypeScript SDK `StreamableHTTPClientTransport`. The local browser E2E suite starts the API and TanStack Start app on explicit non-default ports and exercises the dashboard, charts, memory table, source ingest, graph explorer, operations readiness, admin settings, MCP setup panel, and a real browser OAuth callback listener for MCP bearer-token exchange. The hosted browser smoke additionally covers Better Auth signup, profile/workspace updates, team member invite/remove, dashboard-managed MCP OAuth client registration/disable, browser OAuth callback verification, seeded OAuth connection revocation, readiness, recall, forget, and confirmed account deletion. Optional clean container reproduction: ```sh bun run test:integration:docker ``` If Docker Hub credential or metadata lookup is unavailable but a previously built OpenMemory test image exists locally, run the same Wrangler integration suite against the current checkout mounted into that cached image: ```sh bun run test:integration:docker:cached ``` Optional heavier local scale check: ```sh bun run test:scale:local OPENMEMORY_SCALE_GRAPH_SIZE=1000 bun run test:scale:local ``` Benchmark runs write ignored JSONL evidence under `.tmp/benchmark-reports/`, including recall-quality scores, graph size, recall latency, and asserted thresholds. Optional hosted graph benchmark: ```sh bun run test:benchmark:live ``` The live benchmark creates and deletes a synthetic hosted account, imports a bounded graph, measures hosted recall latency, and writes `.tmp/benchmark-reports/live-production.jsonl`. Set `OPENMEMORY_LIVE_BASE_URL` for a non-default deployment and `OPENMEMORY_LIVE_GRAPH_SIZE` to request a size; the test clamps live graph size between 40 and 160 memories. Graph/RAG production review evidence is tracked in [`config/rag-production-review.json`](config/rag-production-review.json). Normal CI validates the status artifact with `bun run rag:production-review:status`; the strict launch gate is `bun run rag:production-review:check` and is expected to fail until hosted graph benchmark trend, semantic RAG trace review, and rerank threshold review are recorded. Convert external MemoryBench-style JSON or JSONL fixtures into an OpenMemory graph export for local restore/import evaluation: ```sh bun run benchmark:import -- fixtures/memorybench.example.jsonl --out .tmp/memorybench-export.json ``` Optional live checks: ```sh bun run --cwd apps/api test:live bun run test:e2e:ui ``` The live checks require a reachable deployment and any environment required by the target workflow. They cover hosted auth, graph recall, readiness snapshots, R2 export, OAuth/MCP, browser OAuth callback capture, and browser-session readiness access. ## Roadmap Current priorities: - Polish hosted onboarding and dashboard navigation from alpha feedback. - Keep the hosted TanStack Start app as a companion dashboard/control plane while API and MCP integrations remain the primary product surfaces. - Expand charts and the knowledge map for graph health, recall quality, index freshness, and MCP usage. - Expand recall quality benchmarks with larger MemoryBench-style fixtures. - Compare recurring hosted graph benchmark artifacts with local benchmark reports before broad hosted usage. - Complete the strict MCP vendor dogfood gate for MCP Inspector, Cursor, Claude, and ChatGPT after the generic browser callback verifier is green. - Complete the strict social OAuth dogfood gate for GitHub and Google after production OAuth app secrets are installed. - Complete the strict RAG production review gate after hosted graph benchmark trend, semantic RAG trace review, and rerank threshold review are recorded. - Keep Cloudflare Git/Workers Builds as the preferred production deploy path. See [docs/roadmap.md](docs/roadmap.md) for the current working baseline and remaining implementation tracks. ## Docs - [Deployment](docs/deployment.md) - [Operations runbook](docs/operations.md) - [Observability](docs/observability.md) - [Data model](docs/data-model.md) - [Launch announcement](docs/launch-announcement.md) - [MCP setup](docs/mcp.md) - [MCP compatibility](docs/mcp-compatibility.md) - [Roadmap](docs/roadmap.md) - [Launch readiness](docs/launch-readiness.md) - [Release qualification](docs/release-qualification.md) - [Testing strategy](docs/plans/testing-strategy.md) - [Cloudflare memory stack research](docs/research/cloudflare-memory-stack.md) - [Cloudflare RAG bottlenecks](docs/research/cloudflare-rag-bottlenecks.md) - [Graph memory architecture](docs/research/graph-memory-architecture.md) - [Supermemory feature evaluation](docs/research/supermemory-feature-evaluation.md) - [Requirements brainstorm](docs/brainstorms/openmemory-requirements.md) - [Implementation plan](docs/plans/openmemory-plan.md) ## Contributing OpenMemory is MIT licensed. See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), [PRIVACY.md](PRIVACY.md), [SUPPORT.md](SUPPORT.md), and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before opening issues or PRs.