Mimir's Vault

<div align="center">

<img src="assets/readme/hero.svg" alt="Mímir's Vault Banner" width="100%" />

<p align="center"> <b>ᚱ • ᚢ • ᛖ • ᛋ • ᚨ • ᛗ • ᛟ • ᛚ</b><br> <i>"Just as Odin drank from Mímir's Well to gain infinite cosmic wisdom,<br> AI agents require targeted knowledge—not a chaotic ocean of raw files."</i> </p>

---

Key Pillars • System Architecture • Installation • MCP Client Setup • Tool Reference • Agent Workflow Guide

</div>

---

The Problem: Wandering AI Coding Agents

When AI coding agents (Claude Code, Cursor, Antigravity) work on complex software repositories, they frequently suffer from Context Inflation & Wandering:

• They blindly grep directories, re-scan full codebases, and load 30+ unrelated files into memory.
• They waste thousands of LLM tokens, increase execution latency, and lose track of core architectural rules.

---

The Solution: Mímir's Vault Memory Graph

Mímir's Vault (Mimirs_Vault) is a high-performance Model Context Protocol (MCP) server built in Python (FastMCP).

It maintains a human-readable, interlinked Obsidian-Wikilink memory graph inside ./.context/ for any software repository.

AI agents follow the Memory-First Scanning Rule:

1. Inspect .context/overview.md via get_root_node.
2. Follow Obsidian wikilinks ([[modules/auth]]).
3. Inspect only the targeted source code files mapped in that module note.
4. Edit zero unnecessary files.

---

Key Pillars

Rune	Pillar	Rationale
ᛗ	Memory-First Protocol	Mandates AI agents to consult .context/overview.md before reading project source code.
ᛟ	Obsidian-Wikilink Graph	Interlinked notes ([[modules/auth]]) viewable natively in Obsidian, VS Code, and Foam graph visualizers.
⚡	Zero Token Waste	Reduces context consumption by up to 80%, eliminating agent codebase wandering.
⚔️	Surgical Node Updates	Tools to append, update, and log Architectural Decision Records (ADRs) without clobbering existing notes.
ᛚ	Human & Agent Shared Memory	Clean Markdown files (.context/) readable by both human developers and LLMs alike.

---

System Architecture

<div align="center"> <img src="assets/readme/architecture.svg" alt="Mímir's Vault Architecture Flowchart" width="100%" /> </div>

<your-project-root>/
└── .context/                        <-- Memory Graph Root (Ignored in .gitignore)
    ├── overview.md                  <-- ROOT NODE (Scope, File Structure Map, [[modules/*]] index)
    ├── decisions.md                 <-- Architectural Decision Records (ADRs)
    └── modules/                     <-- LINKED MODULE NODES
        ├── auth.md                  <-- Module Note (Scope, Mapped Source Files)
        ├── database.md              <-- Module Note
        └── ui/                      <-- Submodule Directory
            └── components.md        <-- Submodule Note ([[modules/ui/components]])

---

Installation

Prerequisites

• Python 3.10+

1. Clone the Repository & Initialize Environment

# Clone repository
git clone https://github.com/GopikChenth/Mimir-s_Vault.git
cd "Mimir-s_Vault"

# Create virtual environment & install dependencies
python3 -m venv .venv
.venv/bin/pip install "fastmcp>=3.4.0" "mcp>=1.2.0" "pydantic>=2.0.0"

2. Verify Installation & Test Graph Engine

.venv/bin/python test_graph.py

Expected Result: ALL TESTS PASSED SUCCESSFULLY!

---

MCP Client Setup

Add Mimirs_Vault to your preferred AI Client configuration:

Google Antigravity IDE (agy.json / Settings) or Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "Mimirs_Vault": {
      "command": "<path-to-repo>/.venv/bin/python",
      "args": [
        "<path-to-repo>/main.py"
      ]
    }
  }
}

Note: Replace <path-to-repo> with the absolute path where you cloned Mimir-s_Vault (e.g. /home/user/projects/Mimir-s_Vault or C:/Projects/Mimir-s_Vault).

Cursor IDE

1. Open Cursor Settings → Features → MCP Servers.
2. Click + Add New MCP Server.
3. Name: Mimirs_Vault
4. Type: command
5. Command: <path-to-repo>/.venv/bin/python "<path-to-repo>/main.py"

---

MCP Tool Reference

Mimirs_Vault exposes 7 core tools for AI agent navigation:

Tool	Signature	Purpose
get_root_node	(workspace_path: str = ".")	Fetches .context/overview.md (Project Scope, Master File Structure Map, [[modules/*]] index).
navigate_node	(node_path: str, workspace_path: str = ".")	Traverses a wikilink node (e.g. modules/auth, decisions). Returns content & mapped source files.
search_nodes	(query: str, workspace_path: str = ".")	Performs keyword and topic search across all .context/ markdown notes.
init_context_graph	(project_name, description, scope, workspace_path)	Bootstraps .context/ folder with starter overview.md and decisions.md.
create_module_node	(module_name, scope, source_files, parent_node)	Creates a module note and registers [[modules/name]] in the parent node.
update_node	(node_path, content, section_heading, mode)	Surgically appends or replaces content under a specific section heading.
log_decision	(title, context, decision, consequences)	Appends an Architectural Decision Record (ADR) in .context/decisions.md.

---

System Prompts & Resources

MCP Prompts

• memory_first_workflow: Instructs AI agents: "Consult get_root_node first. Read ONLY the target source files mapped in module wikilinks."
• bootstrap_project_context: Guides AI to auto-scan an un-documented repository and build .context/ notes.

MCP Resources

• context://root — Direct read of .context/overview.md.
• context://decisions — Direct read of .context/decisions.md.

---

Agent Workflow Guide

1. Bootstrapping a New Repository

In any project workspace, prompt your AI agent:

"Run the bootstrap_project_context prompt to initialize the memory graph for this repository."

The AI will call init_context_graph and create_module_node to build your project's .context/ tree.

2. Daily Task Execution

When asking your AI agent to implement a feature:

"Implement user authentication with JWT. Check the memory graph first."

The AI will:

1. Call get_root_node to inspect .context/overview.md.
2. Follow [[modules/auth]] to extract mapped file paths (src/auth/service.py).
3. Inspect & edit only src/auth/service.py (zero token waste).

3. Logging Architecture Decisions

"Log an architectural decision that we switched to RS256 JWT signing."

The AI calls log_decision, appending ADR-002 to .context/decisions.md.

---

Visualizing Your Memory Graph in 3D

Because all nodes use standard Obsidian Wikilink syntax ([[modules/auth]]), open your repository's .context/ directory in:

• Obsidian
• VS Code Foam Extension

Enjoy an interactive, 3D visual graph of your codebase's architectural memory!

---

<div align="center">

ᛗ Built with Wisdom for AI-First Engineering ᛗ

Crafted with Python FastMCP • Report Issue • Submit Request

</div>