# Markdown Memory Context MCP 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.

[](https://drive.google.com/file/d/1kbZAplGSrU3TpAL1zCagvWG7AK1iv_uY/view?usp=sharing)

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:

```bash
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:

```json
{
  "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:

```text
.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:

```text
.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.