<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>

  [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
  [![MCP Protocol](https://img.shields.io/badge/Model_Context_Protocol-v1.0-8A2BE2?style=for-the-badge&logo=anthropic&logoColor=white)](https://modelcontextprotocol.io)
  [![FastMCP](https://img.shields.io/badge/Framework-FastMCP_v3.4-22c55e?style=for-the-badge)](https://github.com/jlowin/fastmcp)
  [![Obsidian](https://img.shields.io/badge/Graph-Obsidian_Wikilinks-7C3AED?style=for-the-badge&logo=obsidian&logoColor=white)](https://obsidian.md)
  [![License](https://img.shields.io/badge/License-MIT-f59e0b?style=for-the-badge)](LICENSE)

  ---

  [Key Pillars](#key-pillars) • [System Architecture](#system-architecture) • [Installation](#installation) • [MCP Client Setup](#mcp-client-setup) • [Tool Reference](#mcp-tool-reference) • [Agent Workflow Guide](#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>

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

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

```bash
.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`)

```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](https://obsidian.md)
* VS Code [Foam Extension](https://foambubble.github.io/foam/)

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](https://github.com/GopikChenth/Mimir-s_Vault/issues) • [Submit Request](https://github.com/GopikChenth/Mimir-s_Vault/issues)

</div>