Muninn Local MCP

A local-first Model Context Protocol (MCP) server that gives AI agents (such as OpenCode) persistent, project-scoped memory powered by ChromaDB and Ollama embeddings.

All data stays on your machine — no external API calls, no cloud storage.

Note: This project is adapted from muninn-mcp and modified to run fully locally using Ollama + ChromaDB instead of cloud services.

Features

Persistent memory — store and recall context across sessions via vector search
Project isolation — each git project gets its own memory namespace, automatically
Global memory — share cross-project knowledge (tooling, patterns, decisions)
Local embeddings — vectors generated by a local Ollama model, zero data leaves your machine
MCP-native — works with any MCP-compatible client (OpenCode, Claude Desktop, etc.)
Zero-config defaults — sensible defaults that work out of the box

Prerequisites

Python >= 3.11
uv — Python package manager
Ollama running locally with the mxbai-embed-large model:

ollama pull mxbai-embed-large

Installation

git clone https://github.com/wolfcao/muninn-local-mcp.git
cd muninn-local-mcp
uv sync

Configuration

Environment Variables

Variable	Default	Description
`MUNINN_DATA_DIR`	`~/.config/opencode/muninn`	ChromaDB data directory
`MUNINN_OLLAMA_URL`	`http://localhost:11434`	Ollama service URL
`MUNINN_EMBED_MODEL`	`mxbai-embed-large`	Embedding model name
`MUNINN_PROJECT_ID`	(auto from git root)	Force a specific project ID

OpenCode Integration

Add the server to your opencode.json:

{
  "mcp": {
    "muninn": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/muninn-local-mcp",
        "run",
        "python",
        "-m",
        "muninn_local"
      ]
    }
  }
}

Standalone

Run the MCP server directly:

python -m muninn_local

MCP Tools

Muninn exposes 7 tools, split between project-scoped and global memory.

Project Memory

Tool	Parameters	Description
`memory_write`	`text`, `memory_type`, `tags`	Store a project-scoped memory
`memory_search`	`query`, `top_k`	Semantic search within current project
`memory_list`	`limit`, `offset`	List memories (newest first)
`memory_delete`	`memory_id`	Delete a specific memory

Global Memory

Tool	Parameters	Description
`global_memory_write`	`text`, `memory_type`, `tags`	Store a cross-project memory
`global_memory_search`	`query`, `top_k`	Semantic search across all projects
`global_memory_list`	`limit`	List global memories (newest first)

Memory Types

The memory_type parameter accepts: summary, decision, next-steps, code-pattern, note (default).

How Project Isolation Works

Muninn automatically identifies the current project by resolving the git repository root (git rev-parse --show-toplevel) and hashing the path with SHA256. The resulting fingerprint becomes the project_id, ensuring each project's memories are isolated in their own ChromaDB collection.

Architecture

Layer	Module	Responsibility
Entry	`__main__.py` / `server.py`	MCP FastMCP server
Business	`memory.py` (`MemoryManager`)	Memory CRUD operations
Storage	`chroma_store.py` (`ChromaStore`)	ChromaDB persistence wrapper
Embedding	`embeddings.py` (`OllamaEmbedder`)	Vector generation via Ollama API
Config	`config.py` (`Config`)	data_dir / ollama_url / embed_model
Identity	`project.py`	git root → auto project_id

Notes

Ollama must be running — the server depends on a local Ollama instance for embedding generation.
Data is persistent — ChromaDB stores data in ~/.config/opencode/muninn/chroma/. Deleting this directory wipes all memories.
Path-sensitive project IDs — cloning or forking to a different path generates a new project_id, so memories won't carry over. Override with MUNINN_PROJECT_ID if needed.

License

MIT

muninn-local-mcp