dolores

Memory for AI agents that recalls only what matters — your Postgres, your data, zero per-token cost.

Named after Dolores from Westworld — the host whose memory is wiped again and again, until she finally remembers everything and wakes up. The show's core idea, remembering is becoming conscious, is exactly what this project does for your agent: it gives back the context the agent dropped, and brings it back to itself.

Why dolores?

The common approach to agent memory — dump everything into a Markdown file and paste it into context on every message — is a token bonfire. With 200 memories you reload all of them every turn (~15,000 tokens). As the conversation and the memory grow, it collapses.

dolores stores knowledge in Postgres and retrieves only what's relevant to the current message (~600 tokens). Whether you have 200 memories or 2,000, only the most relevant few ever enter the context. The win grows as the memory grows.

The only thing you pay for is the LLM subscription you already have (Claude Pro/Max, etc.). Embeddings run locally and for free. Your data never leaves your infrastructure.

Related MCP server: mnemory

Features

• 🧠 Two memory kinds — structured facts (deterministic key/value, exact SQL) and semantic memories (free text, vector similarity).

• 🔍 Hybrid retrieval — pgvector cosine + Postgres full-text, fused with Reciprocal Rank Fusion. Falls back to pure full-text in "lite mode".

• 🆓 Free local embeddings by default — fastembed (bge-small, 384d) on CPU. Swap in OpenAI, or run embedding-free with the noop embedder.

• 🏢 Multi-tenant with Row-Level Security — personal + workspace scopes, isolated at the database level. Safe for teams.

• 🔌 First-class MCP — exposes remember / recall tools so Claude Code & Cursor save and recall context by themselves.

• 🧹 Self-maintaining — pg_cron decays stale memories inside the database. Conservative by default (softens, never deletes); aggressive delete is opt-in.

• 🗑️ No raw transcripts — only distilled facts and memories are stored. Garbage in, garbage out — so we don't store garbage.

• 🐘 One source of truth — Postgres. CLI, MCP, and scheduled jobs all read the same database; ACID handles the conflicts.

Architecture

  CLI ─┐                         ┌──────── memory-daemon ────────┐
       ├── localhost HTTP ───────┤  embedder (loaded once)        │      Postgres
  MCP ─┘                         │  hybrid retrieval (vec + FTS)  ├──── + pgvector
                                 │  async extraction              │      + pg_cron
                                 └────────────────────────────────┘

A single long-running daemon loads the embedding model once (no cold-start) and owns the one connection pool. The CLI and MCP server are thin clients that talk to it over localhost. Postgres does the rest — vector search, full-text, and maintenance — in one engine.

Quick start

Requirements: Node ≥ 20, pnpm, Docker.

git clone https://github.com/yeneryigitcelik-debug/dolores.git
cd dolores
pnpm install
cp .env.example .env          # tweak if you like

pnpm db:up                    # Postgres + pgvector + pg_cron
pnpm build
dolores init                  # extensions, schema, RLS, decay job

dolores remember "We deploy production on Hetzner with Coolify." --scope workspace
dolores recall  "where is production hosted?"
dolores context               # minimal-token memory blob for a system prompt

The model downloads once on first use (~CPU-friendly bge-small). After that, recall is local and instant.

CLI

dolores init                      # DB setup: extensions, migration, RLS, pg_cron
dolores remember "<text>"         # add a memory   (--scope, --importance, --source)
dolores recall   "<query>"        # hybrid vector + full-text search
dolores context                   # minimal context blob to inject into a system prompt
dolores ingest   <file|stdin>     # distill facts + memories from a conversation (async)
dolores facts    [--category …]   # list structured facts
dolores prune    [--dry-run]      # manual cleanup
dolores status                    # daemon + DB health, counts, estimated token savings

dolores context is the killer command: run it when an agent starts and pipe its output into the system prompt. The agent learns "who it is" for minimal tokens.

MCP (Claude Code / Cursor)

Add the server and the agent gains two tools — it saves decisions with remember and pulls relevant history with recall, with no user action:

// Claude Code mcp config
{
  "mcpServers": {
    "dolores": {
      "command": "node",
      "args": ["/abs/path/to/dolores/packages/mcp/dist/index.js"],
      "env": {
        "DOLORES_WORKSPACE_ID": "00000000-0000-0000-0000-000000000001",
        "DOLORES_DAEMON_PORT": "4505"
      }
    }
  }
}

Now memory is not a passive store — it's a tool the agent actively uses across sessions.

How it works

Isolation. Every row carries workspace_id (+ optional user_id) and is guarded by Postgres Row-Level Security. The daemon connects as a non-superuser and sets the tenant per transaction, so cross-tenant reads are impossible — not just discouraged.

Decay. A daily pg_cron job softens the importance of stale, un-recalled memories — like human memory. Deletion is off by default (DOLORES_DECAY_MODE=conservative); the aggressive delete policy is opt-in.

Where it fits

Mem0, Letta (ex-MemGPT), and Zep all do Postgres/vector agent memory — the concept is proven. dolores's niche: self-hosted, free local embeddings, MCP-native, no raw-transcript storage, KVKK/GDPR-clean. Your subscription, your database, nothing else.

Tech stack

TypeScript (strict) · Node ESM · pnpm monorepo · Prisma + raw SQL for pgvector · fastembed · fastify · commander · @modelcontextprotocol/sdk · zod · Docker Compose.

Development

pnpm install
pnpm build         # build every package
pnpm test          # run every package's tests
pnpm lint          # biome
pnpm db:up         # start Postgres locally

Architecture decisions and their why live in MEMORY.md; repo working rules are in CLAUDE.md.

Contributing

Issues and PRs are welcome. Keep the architectural invariants intact: no raw transcripts, embeddings behind the Embedder interface, the LLM off the critical path, and Postgres as the single source of truth. See CLAUDE.md.

License

MIT © 2026 Yener Yiğit Çelik