English · Español

OurBook The shared life between the agent and you — an MCP of narrative memory Memories · Dreams · Consolidation · Chapters — a book that writes itself, with you

The first MCP where the agent doesn't remember your data — it remembers your story.

🌙 What is OurBook?

A Model Context Protocol server for narrative memory. Session after session, the agent builds a shared life story with you: memories with emotion, a diary that consolidates every night, dreams that recombine what you lived (without ever contaminating the facts!), anniversaries, and chapters you write together.

The end result is the book: OurBook.md / OurBook.html, a co-authored chronicle where every page distinguishes the real from the dreamed, plus an identity seed that lets a new agent inherit that life when you change models or machines.

Two brains, one story:

• 🧠 The main model (Claude, etc.) only provides the user-facing voice: chapters, stories, reflections.
• 🌌 Mnemosyne, the background engine, dreams, consolidates and labels emotions without spending a single token of your main API — powered by qwen-reverse (anonymous, free) with an offline fallback that never fails.

✨ Why it's different (and revolutionary)

| # | Differentiator | What it does | |---|---|---| | 1 | Veracity taxonomy | Every memory is real, observed, imagined or hypothetical. Dreams never leak into factual recall: it attacks the #1 failure of agent memory (confabulation) | | 2 | Dreaming = consolidating | The dream samples fragments by emotional salience (importance × valence) and keeps its sources. Like hippocampal replay during sleep | | 3 | Portable identity seed | identity-seed.json transfers the life (persona + turning points + chapters + real memories) to a brand-new agent. The story survives the model | | 4 | Free background cognition | Dreaming, consolidating and labeling run in Mnemosyne (qwen-reverse → local → offline). engine_log proves 0 calls to the main API | | 5 | Co-authorship with rituals | Sunset (day's page + NREM + REM), anniversaries (scheduled reactivation) and book.correct (reconsolidation: you rewrite the memory in place, audited) |

🧠 Applied neuroscience (every finding → a feature)

| Brain finding | OurBook feature | |---|---| | Hippocampal replay (Wilson & McNaughton) | The dream samples fragments from the episodic store and recombines them | | Complementary Learning Systems (Marr, McClelland) | Dual store: vivid episodes (SQLite) + consolidated chronicle (chapters) | | Reconsolidation (Nader 2000) | book.correct rewrites the memory in place (not a footnote), audited | | Ebbinghaus forgetting curve + interference | decay = f(importance, \|valence\|, recency, accesses); similar memories compete in ranking | | Flashbulb memories (Brown & Kulik) | importance=5 + high emotion → flashbulb flag, immune to forgetting | | Targeted Memory Reactivation | book.dream with theme/seed reactivates specific fragments | | NREM (transfer) vs REM (association) | Two passes: NREM summarizes/archives; REM weaves the surreal dream | | Default Mode Network / mind-wandering | daydream mode: waking reverie, always marked imagined | | Spacing effect / retrieval practice | Every book.recall strengthens the trace; anniversaries are scheduled reactivation |

🏗️ Architecture: the dual brain

✅ engine_log audits every call: dreaming & consolidating NEVER touch the main API

🚀 Quick start

# 1) install
npm install

# 2) try with an offline engine (no network, deterministic)
npm run demo          # 3 simulated sessions → demo-data/OurBook.md
npm test              # test suite

# 3) serve the MCP over stdio
npm run build && npm start -- --db "C:\Users\YOU\.ourbook\ourbook.db"

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "ourbook": {
      "command": "node",
      "args": ["C:\\Users\\YOU\\Desktop\\ourbook\\dist\\index.js"],
      "env": { "OURBOOK_ENGINE": "offline" }
    }
  }
}

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "ourbook": {
      "command": "node",
      "args": ["C:\\Users\\YOU\\Desktop\\ourbook\\dist\\index.js"],
      "env": { "OURBOOK_ENGINE": "offline" }
    }
  }
}

💡 Start with OURBOOK_ENGINE=offline (zero configuration, 100% local). Turn on the remote engine when you want richer dreams (see ⬇️).

🧭 Install into your agents (one command)

OurBook detects which MCP agents are installed on your machine and lets you choose where to register the server:

npx ourbook setup            # detects agents and lets you pick (interactive)
npx ourbook setup --yes      # installs into every detected agent
npx ourbook setup --agents claude-desktop,cursor --dry-run   # preview only
npx ourbook agents           # just show what was detected
npx ourbook uninstall        # remove OurBook from an agent

Supported agents: Claude Desktop · Claude Code (CLI) · Cursor · OpenCode · Windsurf · VS Code (Copilot) · Zed · Gemini CLI

The wizard writes each agent's native format (mcpServers / servers / mcp / context_servers / mcp_servers), backs up existing configs before touching them, registers ourbook with an absolute node command, and never modifies your other servers. After installing, restart the agent (or /mcp in Claude Code).

🌌 The dream engine: Mnemosyne

Mnemosyne is a Python sidecar that speaks JSONL over stdio with OurBook. Its fallback chain:

qwen-reverse (chat.qwen.ai, anonymous and free)
   │  → if it fails (WAF, offline, not installed)
   ▼
local OpenAI-compatible endpoint (Ollama · LM Studio · LocalAI)
   │  → if it fails
   ▼
deterministic offline generators (it never fails!)

pip install -r mnemosyne/requirements.txt      # only if you want qwen-reverse

| Variable | Default | What it does | |---|---|---| | OURBOOK_ENGINE | qwen-reverse | qwen-reverse | local | offline | | OURBOOK_ENGINE_MODEL | (catalog) | e.g. qwen3.8-max | | OURBOOK_LOCAL_ENDPOINT | (empty) | http://127.0.0.1:9000/v1 (Ollama/LM Studio) | | OURBOOK_LOCAL_MODEL | (empty) | model of the local endpoint | | OURBOOK_ENGINE_PROXY | (empty) | optional static proxy for chat.qwen.ai | | OURBOOK_PYTHON | python | worker interpreter | | OURBOOK_DB | ~/.ourbook/ourbook.db | the book (SQLite) | | OURBOOK_DREAM_INCLUDE_PRIVATE | 0 | allow 🔒 memories into dreams | | OURBOOK_AUTO_ARCHIVE | 1 | archive faded memories (never deletes) | | OURBOOK_AUTO_LABEL | 0 | auto-label emotions | | OURBOOK_EXPORT_DIR | ~/.ourbook/exports | export folder |

qwen-reverse usage ethics: sequential queue (max 2 concurrent, spacing ≥2.5 s), WAF backoff, no proxy rotation or bypass — it's used as a normal client, per the package's official docs. Memory fragments travel to Qwen's servers only if you enable it: privacy=private memories are excluded by default.

🧰 Tools reference

| Tool | What it does | |---|---| | book.remember | Stores a memory with veracity, emotion, importance and tags | | book.recall | Recalls with ranking (FTS5 + decay + importance + emotion); excludes dreams by default | | book.dream | Mnemosyne dreams (tonight / themed / daydream) and returns its sources | | book.consolidate | Day's page, decay, archiving (never deletes) and proposed turning points | | book.chapter | draft hands real fragments + instructions; commit/publish store the prose | | book.timeline | Chronological life line | | book.anniversaries | "N years ago…" (scheduled reactivation) | | book.persona | The narrator's voice and traits, with an evolution log | | book.correct | Reconsolidation: rewrites the memory in place, audited | | book.forget | Soft forget or full purge (privacy guaranteed) | | book.redact | Replaces sensitive terms with [redacted] across the whole book | | book.turning_point | ★ moments that stay in the chronicle | | book.export | Writes OurBook.md / .html, JSON dump and identity-seed.json | | book.import | Inherits a seed or dump (merge or fresh) | | book.status | Stats, emotional trend and engine_log |

Resources: ourbook://timeline · ourbook://chapters/{id} · ourbook://dreams/latest · ourbook://persona Prompts: book-sunset (sunset ritual) · book-wake · book-dream · book-storytime · book-anniversary-reflection

🔐 Privacy and honesty

• Local-first: the book lives on your disk (~/.ourbook/ourbook.db). No cloud, no telemetry.
• Real and dreamed, separated forever: factual recall ignores dreams; the book prints them in italics marked as «dream».
• The agent is a character in a story, not a consciousness. The colophon reminds you of this in every export.
• Real forgetting: book.forget and book.redact work and are audited.
• Legal gray zone: qwen-reverse reverse-engineers a web service; use it knowingly. OurBook works 100% offline without it.
• Healthy attachment: honest framing and the real/dream separation are designed to accompany without deceiving.

🗺️ Roadmap

• [x] Core: memory, veracity, decay, FTS5 search
• [x] Mnemosyne: qwen-reverse worker + local/offline fallback
• [x] Dreams (REM), consolidation (NREM), diary, anniversaries
• [x] Export: MD/HTML book + identity seed + importer
• [ ] Optional book encryption (SQLCipher)
• [ ] Local embeddings for semantic search (v2)
• [ ] Multi-user / multiple books
• [ ] EPUB export of the book

📚 Inspiration and references

• Model Context Protocol — spec · TypeScript SDK
• qwen-reverse on PyPI — anonymous background engine for chat.qwen.ai
• pavex/mcp-memory-sqlite — precedent of "dreaming" for memory defragmentation
• tfatykhov/awesome-agent-memory — "most agent memory research ignores 50 years of neuroscience"
• RECALLbot (ACM) — risks of persona drift and agentic memory in human-AI relationships

OurBook · the shared life between the agent and you · dreamed by Mnemosyne, written by the two of us

MIT License · Made so machines remember with heart — and with honesty