Muninn Local

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

1. Ollama must be running — the server depends on a local Ollama instance for embedding generation.
2. Data is persistent — ChromaDB stores data in ~/.config/opencode/muninn/chroma/. Deleting this directory wipes all memories.
3. 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