moss-brain

Turn everything you've ever written — or watched, or read — into a connected second brain. No LLM, no cost, no waiting.

Dump in your notes, PDFs, YouTube links, article URLs — and your entire conversation history from Claude, ChatGPT, and Gemini. moss-brain embeds all of it locally with Moss, discovers the connections between your ideas in seconds, writes them into your Obsidian vault as real [[wikilinks]], and serves one shared memory back to all of those AIs over MCP at ~2ms per recall — with memory they can write to, not just read.

This is a real vault — 559 notes, 2,819 connections, built in 27 seconds with zero LLM calls, rendered natively by Obsidian:

Blue = imported conversation archive · purple = knowledge articles · green = captures · amber/red = active context. Every edge was discovered from embedding similarity — no model ever "read" the notes.

your files & links ──▶ ingest ──▶ searchable brain (local, ~2ms recall)
                         │
                         ├──▶ connect ──▶ knowledge graph + [[wikilinks]] in Obsidian
                         ├──▶ watch ────▶ auto-index as you write
                         ├──▶ remember ─▶ timestamped episodic memory
                         └──▶ serve ────▶ 6 memory tools for Claude / Hermes / Cursor

Quick start

pip install git+https://github.com/Naut1cal5/moss-brain
moss-brain init                    # paste 2 free keys from moss.dev — 30 seconds
moss-brain ingest ~/Documents/notes ~/Downloads/claude-export/ \
    "https://youtube.com/watch?v=..." "https://any-article.com/..."
moss-brain connect --write-links ~/Documents/notes

That's it. Open Obsidian's graph view and watch your notes organize themselves. Then ask it anything:

$ moss-brain ask "what did that lecture say about attention mechanisms"
(2.9 ms)
[0.812] [youtube/stanford-cs25-transformers — Attention] ...
[0.798] [notes/deep-learning.md — Self-Attention] ...

Related MCP server: memory-mcp

Why this is different

Most second-brain systems today use one of three architectures, each with real strengths. moss-brain explores a fourth trade-off: keep the LLM out of the write path entirely.

The insight: an embedding model already placed every idea in a semantic space when it indexed them, so the relationships are sitting there for free. moss-brain just asks the index "what's nearest to this note?" — a local ~2ms query per note — and the nearest neighbors become weighted edges. Related ideas cluster, recurring themes become hubs, and the entire graph rebuilds in seconds every time you add material.

moss-brain also takes a different storage approach than agent-memory platforms like Mem0 and Letta/MemGPT (both excellent at what they do): here, the memory is your vault — plain markdown you own, browse in Obsidian, and grep like any other file.

Command reference

What can it ingest?

Getting your history out of each AI

Then one command, regardless of source:

moss-brain ingest ~/exports/

moss-brain doesn't hardcode each vendor's schema. Claude, ChatGPT, and Gemini exports are recognized natively; everything else goes through a universal parser that walks any JSON for role/content message structures (role/sender/author × content/text/parts, nested or flat, Unix or ISO timestamps). Tested against DeepSeek, Kimi, and Grok-style exports — and it'll almost certainly swallow whatever format the next frontier lab invents. Markdown exports need no parser at all: they're already the native format.

moss-brain ingest "https://www.youtube.com/watch?v=VIDEO_ID"
#   + fetched — full transcript, titled via oembed, chunked, connected

moss-brain ingest "https://en.wikipedia.org/wiki/Zettelkasten"
#   + fetched — article text extracted and indexed

Everything you feed it joins the same semantic space: a lecture you watched links itself to the notes you wrote about it. Chat exports are sanitized at ingest (role-tag patterns like Human: are neutralized) so agent frameworks can safely read the chunks later.

Your Obsidian vault, self-organizing

connect --write-links appends an idempotent ## Related (moss-brain) block to each note with its strongest semantic neighbors as [[wikilinks]]. Obsidian's native graph view picks them up instantly — no plugin required. Re-run any time; blocks are replaced, never duplicated.

Pair it with watch and the brain maintains itself:

moss-brain watch ~/Documents/notes                    # indexes as you write
moss-brain connect --write-links ~/Documents/notes    # re-link whenever

Give your AI agent a real memory

moss-brain serve is an MCP server exposing six tools — read and write:

memory_remember is what turns a search index into a brain. When your agent learns something mid-conversation — a decision you made, a preference, a deadline — it saves the memory and every future conversation can recall it. Memories land in remembered/YYYY-MM-DD.md inside your vault: plain markdown you can read, edit, and see in your Obsidian graph like any other note.

recent=True solves the classic RAG failure where a question about now surfaces something from eight months ago: dated chunks get an exponential recency boost (score × (0.45 + 0.55·e^(−age/45d))), undated evergreen notes are unaffected.

Hermes Agent — one command

moss-brain hermes --install

It backs up and edits ~/.hermes/config.yaml, prompts for keys if missing, and enables the MCP toolset. Restart your gateway — done. Your Discord/ Telegram bot now:

• recalls anything you've ever written, mid-conversation (memory_search)

• remembers new facts you tell it, across sessions (memory_remember)

• explores — "what else do I have on this?" (memory_related)

To make memory automatic rather than on-request, add one rule to your ~/.hermes/SOUL.md:

## Memory Rules (highest priority)
- Before answering anything about the user, call memory_search first.
- When the user states a fact, decision, or preference worth keeping,
  call memory_remember with a one-line summary.
- For "current status" questions, use memory_search with recent=true.

That's the difference between a stateless assistant and an agent with your entire history: "you told me about this three weeks ago" instead of "could you remind me what that is?"

Connect to every AI you use

The brain speaks MCP, which every major AI client now supports — so the same memory follows you across Claude, ChatGPT, Gemini, Cursor, and your agents.

Claude Desktop / Claude Code / Cursor — add to the MCP config (claude_desktop_config.json, .mcp.json, or Cursor settings):

{
  "mcpServers": {
    "moss-brain": {
      "command": "moss-brain",
      "args": ["serve"],
      "env": {
        "MOSS_PROJECT_ID": "...",
        "MOSS_PROJECT_KEY": "...",
        "BRAIN_VAULT": "/path/to/your/notes"
      }
    }
  }
}

Gemini CLI / Qwen Code — same block in ~/.gemini/settings.json (or ~/.qwen/settings.json — Qwen Code is a Gemini CLI fork) under mcpServers. Tools are discovered automatically.

Codex CLI (OpenAI) — TOML instead of JSON, in ~/.codex/config.toml:

[mcp_servers.moss-brain]
command = "moss-brain"
args = ["serve"]
env = { MOSS_PROJECT_ID = "...", MOSS_PROJECT_KEY = "...", BRAIN_VAULT = "/path/to/notes" }

OpenCode — in opencode.json:

{
  "mcp": {
    "moss-brain": {
      "type": "local",
      "command": ["moss-brain", "serve"],
      "environment": { "MOSS_PROJECT_ID": "...", "MOSS_PROJECT_KEY": "...", "BRAIN_VAULT": "/path/to/notes" }
    }
  }
}

Antigravity / Windsurf / VS Code / JetBrains — all take the standard mcpServers JSON block above in their MCP settings panel (Antigravity: Settings → MCP Servers → Add; VS Code: mcp.json).

Kimi CLI (Moonshot) — supports MCP via its config; use the same command/args pair. For Kimi K2 running inside Claude Code or OpenCode (the common setup), the brain is already there — MCP servers belong to the client, not the model.

Z.ai GLM / DeepSeek / any Anthropic-compatible model — same story: GLM coding plans and DeepSeek endpoints plug into Claude Code, OpenCode, or Cline as the model, and the client mounts moss-brain. Swap models freely; the memory stays.

ChatGPT — ChatGPT connects to remote MCP servers (Settings → Connectors → Advanced → Developer mode). Run the brain over HTTP and expose it with any tunnel:

moss-brain serve --http --port 8765     # endpoint: http://127.0.0.1:8765/mcp
ngrok http 8765                          # or cloudflared, tailscale funnel...

Paste the public /mcp URL as a new connector — ChatGPT can now search and write to the same brain as everything else.

Anything else — serve is stdio MCP and serve --http is streamable HTTP; between the two, any MCP-capable client (open-source agents, LangChain, custom apps) can mount your brain. One brain, every AI you use, for code and for life.

How it works (technical)

Chunking. Files are split on markdown headings into heading-bounded chunks, each prefixed with [source — heading] and capped at 4,000 chars. Chunk IDs are md5(source#index), so re-ingesting is idempotent — same content, same ID, no duplicates.

Embedding. Moss embeds every chunk locally — nothing leaves your machine during indexing, and there is no per-document cost. After ingest the index persists per your BRAIN_STORAGE choice — a local disk snapshot (~1s restart) or your private Moss project (~1.6s restart) — instead of re-embedding for minutes on every start.

Connections. connect takes each note's first chunk as a probe, runs a local ~2ms nearest-neighbor query, and keeps neighbors above a similarity floor (default 0.35) as weighted edges. 559 notes → 2,819 edges in 27s, zero API calls to any LLM.

Recall. Queries embed locally and search locally: 1.7–3.4ms measured. Works offline once the index is loaded.

Sanitization. Role-tag patterns (Human:, <|im_start|>, [INST], …) are neutralized at ingest so chunks can be safely injected into any agent framework's context without tripping prompt-injection filters.

Episodic memory. memory_remember appends to remembered/YYYY-MM-DD.md in your vault, indexes the entry with its timestamp, and pushes the index — the memory survives restarts and shows up in Obsidian. Recency-aware search reads the date straight from the chunk prefix.

Where your brain lives: local or cloud

Embedding and queries always run locally — the only question is where the index persists between restarts. moss-brain init asks once; override any time with --local / --cloud flags or BRAIN_STORAGE in .env.

moss-brain --local ingest ~/notes     # snapshot to disk, nothing uploaded
moss-brain --cloud ingest ~/notes     # push to your Moss project

⚠️ Local-mode caveats (read before relying on it)

• It uses moss-core APIs not yet in the public Python wrapper (save_to_disk / load_from_disk). moss-brain probes for them and falls back to a cloud push with a printed warning if a future moss release renames them — your data is never lost, but that fallback push does upload. Pin your moss version if this matters to you.

• Startup still makes one network round-trip — MossClient validates your keys, and the SDK reports usage telemetry in the background. Local mode means your content stays home, not that the process is air-gapped.

• Snapshots are per-machine. Two machines in local mode are two independent brains; use cloud mode (or sync ~/.moss-brain/ yourself) to share one.

• Corrupt or partial snapshot (disk full, killed mid-save): the load fails with a warning and moss-brain transparently falls back to cloud resume or re-embedding. Worst case is a one-time indexing wait, never data loss — your source files are always the truth.

Multiple brains

Keep separate brains for separate lives — one flag:

moss-brain -i work ingest ~/work/notes
moss-brain -i work ask "what did the design review decide"
moss-brain -i research ingest "https://arxiv.org/abs/..."

Each -i NAME is an isolated Moss index (BRAIN_INDEX env var works too, e.g. per-agent in MCP config — give each agent its own brain).

Real numbers (559-file vault, M-series MacBook)

FAQ

Does my data leave my machine? Embedding and queries always run locally. In local mode the index snapshots to ~/.moss-brain/ and your content never uploads (see caveats above). In cloud mode the index is pushed to your private Moss project — vectors + chunk text under your own account, same trust model as a private repo.

What does it cost? Nothing. Local embedding and queries are free and unlimited; the moss.dev free tier covers the index persistence.

Do I need Obsidian? No — any folder of markdown works. Obsidian is just the nicest way to see the brain (--write-links + graph view).

Can multiple agents share one brain? Yes — point them at the same BRAIN_INDEX. Or isolate them with one index each.

Something failed mid-ingest? Unreadable files are skipped with a warning, everything else continues. Re-run safely — chunk IDs are deterministic, so nothing duplicates.

License

MIT