Personal Memory Wiki

A persistent personal memory system for Claude, exposed as an MCP server. It accumulates, organizes, and surfaces a single user's knowledge over time. All data is plain Markdown in a git repo: no database, no embeddings, no RAG. Git history is the audit log and the undo button.

The idea: while you talk to Claude, it captures notes into a fast "short-term" layer. A nightly dream then distils those captures into curated long-term pages, the same way memory consolidates during sleep. You can read and edit everything through a private web console.

It is a standalone Python service: a Docker image, an HTTP MCP endpoint, and a named volume holding the wiki. The code is path-agnostic via the WIKI_ROOT environment variable, so it runs the same locally or on any host behind a TLS-terminating reverse proxy.

MCP tools (what Claude calls)

A deliberately small surface (a small surface is easier for the model to use correctly):

• prime() - call FIRST: loads the grounding context (the self/ pages, then the long-term and short-term indexes) in one call.

• read(path) - read any file: a page, an index, or a short-term entry. Tolerant of paths and suggests alternatives on a miss.

• search(query_text, max_results?) - full-text search, returning path:line: text matches.

• remember(content, summary?, tags?, due?, type?) - capture into short-term memory; due/type file dated items (todo, reminder, event) into temporal/.

• GET /health - liveness probe for the Docker healthcheck (public, not a tool).

Writing to long-term memory is intentionally not an MCP tool. It happens through the web console or the nightly dream, never from a live conversation. This keeps structural edits deliberate. All tools honour the owner allow-list and a path guard, so long_term/private/ is never read or searched.

Related MCP server: memory-mcp

How memory is organized

• short-term (short_term/): the open, fast-to-write layer. Every remember appends an entry here.

• long-term (long_term/): curated pages, including a self/ section (identity, grounding) and a private/ section never exposed over MCP.

• temporal (temporal/): dated, transient items (todo / reminder / event) that live until their due date, then are archived. A durable fact with no expiry belongs on a long-term page instead.

• index: each layer has a one-line-per-page index, regenerated by code so it cannot drift from the contents.

The dream (nightly consolidation)

The dream reads short-term memory plus a policy file (DREAM.md, editable in the console) and decides how to fold captures into long-term pages. It runs as a three-stage pipeline so no single call ever needs the whole memory (cost scales with the number of captures, not the wiki size):

1. triage - cluster and route each capture;

2. decide - per unit, reading only the touched pages, choose the action;

3. write - produce each page's final content and its index line.

It has two modes, set from the console (/ui/dream):

• dry-run - stops after stage 2 and writes a report to dream_reports/, changing nothing.

• execute - runs stage 3 and applies everything in one revertible git commit (writes pages, files temporal items, drops consumed short-term entries, expires past-due items). It never deletes long-term content.

A built-in scheduler thread can run the dream once a night (off / dry-run / execute, stored in dream_schedule.json). "Once a day" is enforced by the presence of the day's report, so restarts never double-run and a missed night is caught up. The model is WIKI_DREAM_MODEL (defaults to Opus, overridable per stage via _TRIAGE / _DECIDE / _WRITE) and needs ANTHROPIC_API_KEY. The three stage prompts are editable files (prompts/{triage,decide,write}.md) viewable at /ui/prompts; the JSON schema is injected by code, so editing the guidance cannot break the contract.

Web console (/ui)

A private, browser-facing console served by the same process:

• /ui - lists every markdown file under the wiki (the structure).

• /ui/page/{path} - view a page rendered from markdown.

• /ui/edit?path=... - edit a page (or create one when path is empty).

• POST /ui/save, POST /ui/delete - write or soft-delete, committed with a manual: prefix (soft-delete keeps history).

• /ui/dream, /ui/prompts - run/schedule the dream and edit its prompts.

Markdown is rendered with raw HTML disabled, so stored content cannot inject markup. Forms carry a signed CSRF token.

Authentication: GitHub OAuth + owner allow-list

The server uses FastMCP's GitHubProvider (an OAuth proxy running the OAuth 2.1

• PKCE flow Claude.ai expects). On top of "any valid GitHub login", an allow-list middleware restricts access to a single account (WIKI_ALLOWED_GITHUB_LOGIN), so the wiki stays private to its owner. The browser console uses the same OAuth app.

Configuration (environment variables)

Provide these through your deployment's environment (a .env file, container secrets, an orchestrator, etc.). They are configuration, not committed to the repo.

GitHub OAuth app setup (one time)

Create a GitHub OAuth App (Settings -> Developer settings -> OAuth Apps) with:

• Homepage URL: https://YOUR_DOMAIN

• Authorization callback URL: https://YOUR_DOMAIN/ (GitHub accepts any subpath, so both /auth/callback for Claude and /ui/auth/callback for the console work). Secret names must not start with GITHUB_, which GitHub reserves.

Architecture

• Transport: Streamable HTTP, MCP mounted at /mcp, listening on :8765.

• Data: the wiki lives under WIKI_ROOT (default /srv/wiki), intended to be a persistent volume. The entrypoint seeds it from seed/ only if empty, then git inits it, so restarts never clobber data.

• Public URL: https://YOUR_DOMAIN/mcp, behind a reverse proxy that terminates TLS (Caddy, nginx, Traefik, etc.).

memory-wiki/
  Dockerfile
  docker-entrypoint.sh    # seed-if-empty + git init, then run the server
  pyproject.toml
  src/wiki_server/
    server.py             # FastMCP app: tools + /health
    store.py, query.py    # read / search / write over the markdown tree
    paths.py              # path validation under WIKI_ROOT, refuses private/
    temporal.py           # dated items
    dream/                # the staged consolidation pipeline + scheduler
    ui.py, prompts.py     # web console and editable dream prompts
  seed/                   # initial wiki content, copied into the volume once
  tests/

Run locally

The fast way, with auth disabled (no OAuth needed; the dream needs an Anthropic key, but the read/write tools do not):

docker build -t memory-wiki .
docker run --rm -p 8765:8765 \
  -e WIKI_AUTH_DISABLED=1 \
  -v "$PWD/.localwiki:/srv/wiki" \
  memory-wiki

Then:

curl -s localhost:8765/health        # -> {"ok": true}

npx @modelcontextprotocol/inspector
#   connect to: http://localhost:8765/mcp
#   call prime(), then read("self/identity.md")

The local volume is seeded from seed/ on first run, so you get a working wiki to poke at.

Tests

The logic (store, temporal items, the dream pipeline, path guard, prime) is covered by a fast pytest suite that runs against a throwaway wiki, with git commits and model calls stubbed. No API key or network needed. Runs in CI on every push.

pip install pytest        # or: pip install -e ".[dev]"
pytest -q

Deployment

The image is built from the included Dockerfile. A GitHub Actions workflow (.github/workflows/ci.yml) runs the tests and, on main, builds and pushes the image to GHCR. From there, deploy the container however you like: any Docker host works, as long as the MCP endpoint sits behind a reverse proxy that terminates HTTPS at your public URL and the env vars above are supplied.

Two things to remember in production:

• mount a persistent volume at WIKI_ROOT so the wiki survives restarts;

• point a DNS record for your domain at the host, and let the reverse proxy handle the certificate.

Connect Claude.ai

1. In Claude.ai: Settings -> Connectors -> Add custom connector.

2. URL: https://YOUR_DOMAIN/mcp.

3. Claude redirects you to GitHub to log in and consent. Only the allow-listed GitHub account can use the tools.

4. Ask Claude to call prime(), then read("self/identity.md").

Roadmap

Built so far: OAuth, remember() plus the lean read/search tools, temporal items, the web console, and the staged dream (dry-run, execute, editable prompts, per-stage model, automatic nightly schedule).

Still open: a weekly digest (a periodic summary of what changed and what is coming up). Optional later: notifications, and a "reorg" dream to fold residual duplicate pages.