AI Diary MCP Server

<div align="center">

<img src="docs/banner.png" alt="AI Diary — local-first memory for AI" width="100%" />

<p> <b>A private, local-first MCP server that gives any AI long-term memory — its own diary.</b><br/> Zero models · zero network · zero subscription. Smarter search than Notion, running entirely on your machine. </p>

<p> <img src="https://img.shields.io/badge/TypeScript-5.8-3178c6?logo=typescript&logoColor=white" alt="TypeScript" /> <img src="https://img.shields.io/badge/Node-%E2%89%A520-339933?logo=node.js&logoColor=white" alt="Node" /> <img src="https://img.shields.io/badge/MCP-stdio-7c5cff" alt="MCP" /> <img src="https://img.shields.io/badge/SQLite-FTS5%20trigram-003b57?logo=sqlite&logoColor=white" alt="SQLite FTS5" /> <img src="https://img.shields.io/badge/local--first-100%25%20offline-36d399" alt="Local-first" /> <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT" /> </p>

<p> <a href="#-quick-start">Quick start</a> · <a href="#-the-dashboard">Dashboard</a> · <a href="#-connect-it-to-your-ai">Connect</a> · <a href="#-tools">Tools</a> · <a href="#-why-its-better-than-notion">Why</a> </p>

</div>

---

✨ Highlights

• 🔒 Truly private. Every memory lives in one SQLite file on your disk. Nothing is ever uploaded.
• 🧠 No embeddings, still smart. Retrieval uses SQLite FTS5 + BM25 with a trigram tokenizer, so search is instant and works great for English and 中文 / CJK.
• 🤝 Borrows your platform's brain. When the host supports MCP sampling, recall expands & re-ranks and reflect auto-summarizes — with graceful fallback when it doesn't. The server itself never ships a model.
• 🕸️ A real knowledge graph. Link memories and traverse the web of context.
• 🗂️ Collections, tags, importance, reflection, dedup. Organize like Notion — locally and programmatically.
• 🎨 A beautiful local dashboard. Browse, search, and add memories in your browser (dark & light).
• 🧩 Works everywhere MCP does. Claude Desktop, Cursor, Windsurf, Cline, VS Code, Zed…

🖥️ The dashboard

A polished local web UI over the same database — npm run dashboard, then open http://localhost:4178.

<div align="center"> <img src="docs/dashboard-home.png" alt="AI Diary dashboard — all memories" width="80%" /> <br/><br/> <table> <tr> <td width="50%"><img src="docs/dashboard-tags.png" alt="Tag view" width="100%" /></td> <td width="50%"><img src="docs/dashboard-new.png" alt="New memory" width="100%" /></td> </tr> <tr> <td align="center">_{Tags, including 中文}</td> <td align="center">_{Add a memory in a click}</td> </tr> </table> </div>

Browse · full-text search (English + 中文) · filter by tag/collection · spot near-duplicates · add memories · dark/light theme · one-click git snapshot.

🏆 Why it's better than Notion

	AI Diary	Notion
Privacy	100% local, single file you own	Cloud-hosted
Built for AI	Native MCP tools an agent calls directly	Manual / limited API
Chinese search	FTS5 trigram — precise CJK substring search	Weak
Knowledge graph	First-class links + graph traversal	No
Offline	Always	No
Cost	Free, no subscription	Paid tiers
Versioning	Optional git history of your memory	Limited

🚀 Quick start

git clone https://github.com/pangxianggang/ai-diary-mcp.git
cd ai-diary-mcp
npm install
npm run build      # produces dist/index.js — the stdio MCP server
npm run smoke      # self-test (26 assertions)

Try the dashboard with some sample data:

AI_DIARY_DB_PATH=./demo.db node scripts/seed-demo.mjs
AI_DIARY_DB_PATH=./demo.db npm run dashboard      # http://localhost:4178

Override the port with AI_DIARY_PORT.

🎨 The design philosophy

The server is the hippocampus — fast storage, structure, and retrieval. Your platform's model is the cortex — it reasons, summarizes, and decides what to remember.

The server never calls an LLM and never goes online. That keeps it private, free, and trivially portable.

💾 Where memories are stored

A single SQLite file:

OS	Default path
Windows	%APPDATA%\ai-diary\memory.db
macOS	~/Library/Application Support/ai-diary/memory.db
Linux	$XDG_DATA_HOME/ai-diary/memory.db (or ~/.local/share/...)

Override with AI_DIARY_DB_PATH. Back up by copying the file. Keep it inside a git repo and call snapshot for versioned memory history.

🔌 Connect it to your AI

Use the absolute path to the built dist/index.js.

Claude Desktop

claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "ai-diary": {
      "command": "node",
      "args": ["/absolute/path/to/ai-diary-mcp/dist/index.js"]
    }
  }
}

Cursor / Windsurf / Cline / Zed / VS Code

All use the same shape — command: "node" with args pointing at dist/index.js. Add an env block to relocate the database:

{
  "mcpServers": {
    "ai-diary": {
      "command": "node",
      "args": ["/absolute/path/to/ai-diary-mcp/dist/index.js"],
      "env": { "AI_DIARY_DB_PATH": "/absolute/path/to/my-memory.db" }
    }
  }
}

Restart the client after editing its config.

🧰 Tools

Tool	What it does
remember	Save a memory (content, optional tags, category, importance 1–5, occurred_at). Identical content is de-duplicated.
recall	Search by text (FTS5 BM25, CJK-aware) with optional tags / category / collection_id / time filters. smart=true adds host-model query expansion + re-ranking (with fallback).
recent	List the most recently created memories.
timeline	Browse chronologically by when things occurred.
get	Fetch one memory by id, including its links.
update	Edit an existing memory.
forget	Archive (default) or hard-delete a memory.
link	Connect two memories into a knowledge graph (e.g. caused, related).
graph	Traverse the knowledge graph around a memory (BFS to a depth) and return connected memories + links.
find_duplicates	Surface near-duplicate memories via trigram similarity.
create_collection / add_to_collection / list_collections	Group memories into Notion-like collections.
list_tags	All tags with usage counts.
stats	Totals, categories, time range, db location.
export	Export memories as Markdown.
reflect	Consolidate related memories. auto=true (with host sampling) summarizes and stores the reflection, linked to its sources.
snapshot	Commit the SQLite file to git for versioned memory history.

Resource memory://recent (recent entries as Markdown) · Prompt recall-about (recall + summarize a topic).

🧱 Capabilities by phase

1. MVP — SQLite + FTS5 (CJK trigram) + full CRUD over stdio, one-line client config.
2. Smart retrieval — optional MCP-sampling query expansion + re-ranking in recall, automatic fallback to plain FTS5.
3. Structure — tags, collections, links / knowledge graph traversal, importance, soft-forget.
4. Reflection — reflect auto=true consolidates memories via the host model; find_duplicates for de-duplication.
5. Experience — a polished local web dashboard + Markdown export + optional git-versioned history.

🔍 How search works (without embeddings)

1. FTS5 + BM25 ranks entries by relevance. The trigram tokenizer indexes 3-character sequences, which is what makes substring and CJK search work.
2. Metadata filters (tags, category, collection, time range, importance) narrow results.
3. Queries shorter than 3 characters fall back to a LIKE substring scan.
4. With smart=true, a sampling-capable host expands the query and re-ranks candidates — but the core works fully without it.

🛠️ Development

npm run dev        # tsc --watch
npm run typecheck  # type-check only
npm run smoke      # in-memory end-to-end check (26 assertions)
npm run dashboard  # local web UI

📄 License

MIT