Markdown Memory Context Server

Markdown Memory Context, or MMC, is a local MCP server that gives AI agents structured read and write tools for a folder-based Markdown or Obsidian memory context vault.

The vault is intentionally simple: a top-level Project Index.md, lightweight category hubs, and focused child notes under category folders. Templates live outside the vault in memory-templates/, so agents can read them without cluttering the Obsidian graph.

Quickstart

From this repository:

cd markdown-memory
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
python -m pytest

Configure an MCP client to run the local executable:

{
  "mcpServers": {
    "mmc": {
      "command": "mmc-mcp",
      "args": [],
      "env": {
        "MARKDOWN_MEMORY_ROOT": ".markdown-memory",
        "MARKDOWN_MEMORY_EMBEDDINGS_API_KEY": "..."
      }
    }
  }
}

The older markdown-memory-mcp executable remains available for compatibility. New configs should prefer mmc as the MCP server key and mmc-mcp as the command.

You can also pass memory_root to every tool call. Tool arguments take precedence over MARKDOWN_MEMORY_ROOT; if neither is set, the server uses .markdown-memory in the current working directory.

Vault Layout

Run memory_init to create the base layout:

.markdown-memory/
  Project Index.md
  Architecture.md
  Architecture/
  Commands.md
  Commands/
  Current State.md
  Current State/
  Rules.md
  Rules/
  ...
memory-templates/
  Project Index Template.md
  Category Hub Template.md
  Memory Entry Template.md
  Architecture Entry Template.md
  Commands Entry Template.md
  Rules Entry Template.md
  Ignore Entry Template.md
  Decision Entry Template.md
  Risk Entry Template.md

Category hubs stay short and link to focused notes. Durable details belong in focused notes such as Architecture/Data Flow.md or Rules/Safety And Secrets.md.

Tools

• memory_init: create missing vault hubs, category folders, and templates.
• memory_index: list index, hubs, focused notes, tags, snippets, and presence flags.
• memory_brief: return a compact orientation payload for agents.
• memory_workflow: return the recommended read/write memory workflow.
• memory_context_pack: combine the brief, semantic/lexical matches, and selected reads.
• memory_search: search focused notes by query and optional category.
• memory_vector_status: report whether semantic search is usable, chunk counts, stale notes, model, dimensions, and DB path.
• memory_vector_rebuild: create or refresh the derived vector SQLite index.
• memory_vector_search: semantic search focused notes, with silent lexical fallback.
• memory_read: read one note by key or path.
• memory_upsert: create or replace a focused note.
• memory_append: append a bounded section to a focused note.
• memory_link: ensure a category hub links to a focused note.

Semantic Search

Markdown remains the source of truth. The vector index is derived local state at:

.markdown-memory/.markdown-memory-vector/index.sqlite3

Deleting the SQLite file is safe; rebuild it with memory_vector_rebuild. Vector search uses OpenAI-compatible embeddings:

• MARKDOWN_MEMORY_EMBEDDINGS_BASE_URL, default https://api.openai.com/v1
• MARKDOWN_MEMORY_EMBEDDINGS_API_KEY
• MARKDOWN_MEMORY_EMBEDDINGS_MODEL, default text-embedding-3-small
• MARKDOWN_MEMORY_EMBEDDINGS_TIMEOUT, default 30

For compatibility, the server also accepts the corresponding JARVIS_EMBEDDINGS_* variables when Markdown Memory-specific variables are not set.

If embeddings or the database are unavailable, vector tools return non-fatal metadata and memory_vector_search falls back to memory_search. Memory writes still succeed. memory_upsert, memory_append, and memory_link try to refresh the affected note and hub vectors automatically.

Using With Coding Agents

Use memory as working context, not as a substitute for repository evidence.

1. Start with memory_context_pack, memory_brief, or memory_index.
2. Use memory_vector_search for task terms and categories; lexical search is the fallback.
3. Use memory_read for the smallest relevant focused notes.
4. Inspect source evidence before decisions.
5. Save durable findings with memory_upsert or memory_append.

Prefer memory_append for decisions, risks, workflows, and time-based updates.

Safety

Markdown Memory refuses path traversal, writes outside the configured memory root, secret-like filenames, and secret-like content such as env assignments or private key blocks. It excludes .obsidian/ from index and search results.

Never store secrets, credentials, tokens, private environment values, or API keys in memory notes.