agent-vault-mcp 0.2.0__tar.gz

agent_vault_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: agent-vault-mcp
+Version: 0.2.0
+Summary: DSA-Optimized AI Knowledge Bank MCP Server
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp<3,>=2
+
+# Agent Vault MCP
+
+A blazing-fast, token-efficient AI Knowledge Bank and Memory Server built on the **Model Context Protocol (MCP)**. 
+
+Agent Vault is designed to give AI coding agents (like Claude Code, Antigravity, and Cursor) persistent, cross-session memory without blowing up token limits. It acts as an intelligent file digest cache and semantic knowledge base.
+
+## Overview
+AI agents typically start every session with amnesia, forcing them to re-read thousands of lines of code. Agent Vault solves this using a **Two-Step Funnel**:
+1. **Discovery**: The agent searches the Vault to find out *which* files matter.
+2. **Execution**: The agent reads only the raw code of those specific files, edits them, and updates the vault.
+
+When the agent wants to check a file, the Vault hashes it (SHA-256). If it hasn't changed, the Vault instantly returns a cached AST/summary instead of making the agent read the entire file.
+
+## Features
+- **$O(1)$ Fast Rejection**: Uses Bloom Filters to instantly know if a file is unindexed.
+- **Token-Bounded MinHeap**: Ranks the best context snippets and strictly cuts off when the maximum token limit is reached, protecting the context window.
+- **SQLite FTS5 (BM25)**: Fast lexical and semantic search for symbols, errors, and flows.
+- **ROI Telemetry**: Natively calculates and tracks how many tokens and hours of inference time are saved by skipping raw file reads.
+- **100% Portable**: Caches are stored using relative paths, meaning you can move or rename your project folder without breaking the vault.
+
+## Dependencies
+- Python 3.10+
+- `mcp` (Official Model Context Protocol SDK, `mcp>=2,<3`)
+- Standard library components (`sqlite3`, `hashlib`, `heapq`)
+
+## Installation
+
+### Option 1: Global Python (3.10+)
+```bash
+# Clone or navigate to the repository
+cd agent-vault-mcp
+
+# Install the package
+pip install -e .
+```
+
+### Option 2: Using `uv` (Virtual Environment)
+```bash
+uv venv --python 3.12
+.venv\Scripts\activate  # On Windows
+uv pip install -e .
+```
+
+## How to use with Antigravity / Claude Code
+
+To add this to an MCP client like Antigravity, add the following to your `mcp_config.json` (e.g., `~/.gemini/config/mcp_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-vault": {
+      "command": "python",
+      "args": ["-m", "agent_vault.server"],
+      "env": {
+        "PYTHONPATH": "/absolute/path/to/agent-vault-mcp"
+      }
+    }
+  }
+}
+```
+*Note: If you used a virtual environment, change `"command": "python"` to the absolute path of the python executable inside `.venv`.*
+
+### Adoption (Forcing the AI to use it)
+The Vault only saves tokens if the AI remembers to use it! Add this snippet to your project's `CLAUDE.md`, `.cursorrules`, or `GEMINI.md`:
+
+```markdown
+# 🧠 Agent Vault & Memory Protocol
+You are equipped with the Agent Vault MCP Server. To protect the user's token limits and eliminate hallucination, you MUST strictly adhere to the following workflow:
+
+### 1. The "Think Before You Read" Rule (Semantic Cache)
+Before you spend time reading files to understand an architecture, flow, or system (e.g., "How does auth work?"):
+* **ALWAYS** call `vault_search_questions(query)` using keywords/tags to see if a previous agent already solved this.
+* If you find a match, call `vault_search_answer(prompt)` to retrieve the pre-computed answer instantly.
+
+### 2. The "Read Before You Write" Rule (File Cache)
+Before you execute commands to read raw code files:
+* **ALWAYS** call `vault_check_file(filepath)` first. 
+* If the Vault returns a Cache Hit, trust the summary/AST and DO NOT read the raw file unless you explicitly need to edit it.
+
+### 3. The "Leave It Better Than You Found It" Rule (Updating Cache)
+Your memory is only as good as what you save. After you complete a task:
+* **Cache Modified Files:** If you edited a file, ALWAYS call `vault_cache_file(filepath, summary)` to update its digest and AST.
+* **Cache New Knowledge:** If you just spent time analyzing a complex architecture or debugging a hard issue, ALWAYS call `vault_cache_answer(prompt, response, dependencies, tags)`.
+   * *Dependencies:* You MUST provide the exact file paths your answer relies on so the Vault can auto-invalidate your answer if those files change.
+   * *Tags:* Provide 5-6 broad keyword tags (e.g., "auth, login, jwt") so future agents can easily discover your answer via `vault_search_questions`.
+```
+
+## Local vs Global Vaults
+
+By default, the MCP server creates `agent_vault.db` inside your current active project workspace. Paths are stored **relatively**. This means if you ask the agent about a file in an external project (e.g., `../Project_B/main.py`), that cross-project memory is stored locally inside your current project's database.
+
+If you prefer a **"Global Brain"** that shares all memories and file caches across every single project on your computer, simply add `AGENT_VAULT_DB_PATH` to the `env` variables in your `mcp_config.json`:
+
+```json
+"env": {
+  "PYTHONPATH": "/absolute/path/to/agent-vault-mcp",
+  "AGENT_VAULT_DB_PATH": "/absolute/path/to/.global_agent_vault.db"
+}
+```
+
+## Available MCP Tools
+- `vault_store_memory(key, content, tags)`: Save arbitrary architectural notes or debugging insights.
+- `vault_search(query, max_tokens)`: Search the vault using BM25 ranking.
+- `vault_cache_file(filepath, summary)`: Hash a file and cache its summary.
+- `vault_check_file(filepath)`: Verify a file's hash and return its cached summary + telemetry metrics.
+- `vault_stats()`: View the ROI dashboard of tokens and time saved.
+- `vault_delete_memory(key)`: Delete a stored memory.
+- `vault_evict_file(filepath)`: Evict a file from the vault cache.- `vault_cache_answer(prompt, response, dependencies, tags)`: Save an AI-generated answer linked to specific files and keywords.
+- `vault_search_questions(query, max_results)`: Keyword-search an FTS5 index to find exactly how previous cached questions were phrased based on tags.
+- `vault_search_answer(prompt)`: Retrieve a cached AI answer (automatically invalidates if dependent files have changed).
+
+## Semantic Prompt Caching (Intent Caching)
+
+In `v0.2.0`, Agent Vault introduced **Semantic Prompt Caching**. Instead of forcing AI agents to repeatedly read files and re-reason through complex architectural questions (e.g., *"How does the auth flow work?"*), agents can now cache their reasoning.
+
+### Dependency Invalidation
+To solve the classic LLM problem of "stale context hallucination," Agent Vault uses **Deterministic Dependency Invalidation**. When an agent caches an answer, it explicitly lists the files that answer depends on. 
+
+When a future agent asks the same question, the Vault calculates the real-time SHA-256 digest of those dependencies. If any file has changed, the cached answer is instantly evicted, forcing the AI to generate a fresh, accurate response.
+
+### N-to-1 Tag Mapping
+To solve the problem of "brittle exact matching" (where *"How does login work?"* misses a cache for *"How does the login work?"*), agents can assign **tags** to cached answers. 
+Agents can use `vault_search_questions("login")` to hit the FTS5 index, discover the exact phrasing of the cached question, and then fetch the answer—bypassing the need for heavy vector databases!

agent_vault_mcp-0.2.0/README.md

@@ -0,0 +1,123 @@
+# Agent Vault MCP
+
+A blazing-fast, token-efficient AI Knowledge Bank and Memory Server built on the **Model Context Protocol (MCP)**. 
+
+Agent Vault is designed to give AI coding agents (like Claude Code, Antigravity, and Cursor) persistent, cross-session memory without blowing up token limits. It acts as an intelligent file digest cache and semantic knowledge base.
+
+## Overview
+AI agents typically start every session with amnesia, forcing them to re-read thousands of lines of code. Agent Vault solves this using a **Two-Step Funnel**:
+1. **Discovery**: The agent searches the Vault to find out *which* files matter.
+2. **Execution**: The agent reads only the raw code of those specific files, edits them, and updates the vault.
+
+When the agent wants to check a file, the Vault hashes it (SHA-256). If it hasn't changed, the Vault instantly returns a cached AST/summary instead of making the agent read the entire file.
+
+## Features
+- **$O(1)$ Fast Rejection**: Uses Bloom Filters to instantly know if a file is unindexed.
+- **Token-Bounded MinHeap**: Ranks the best context snippets and strictly cuts off when the maximum token limit is reached, protecting the context window.
+- **SQLite FTS5 (BM25)**: Fast lexical and semantic search for symbols, errors, and flows.
+- **ROI Telemetry**: Natively calculates and tracks how many tokens and hours of inference time are saved by skipping raw file reads.
+- **100% Portable**: Caches are stored using relative paths, meaning you can move or rename your project folder without breaking the vault.
+
+## Dependencies
+- Python 3.10+
+- `mcp` (Official Model Context Protocol SDK, `mcp>=2,<3`)
+- Standard library components (`sqlite3`, `hashlib`, `heapq`)
+
+## Installation
+
+### Option 1: Global Python (3.10+)
+```bash
+# Clone or navigate to the repository
+cd agent-vault-mcp
+
+# Install the package
+pip install -e .
+```
+
+### Option 2: Using `uv` (Virtual Environment)
+```bash
+uv venv --python 3.12
+.venv\Scripts\activate  # On Windows
+uv pip install -e .
+```
+
+## How to use with Antigravity / Claude Code
+
+To add this to an MCP client like Antigravity, add the following to your `mcp_config.json` (e.g., `~/.gemini/config/mcp_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-vault": {
+      "command": "python",
+      "args": ["-m", "agent_vault.server"],
+      "env": {
+        "PYTHONPATH": "/absolute/path/to/agent-vault-mcp"
+      }
+    }
+  }
+}
+```
+*Note: If you used a virtual environment, change `"command": "python"` to the absolute path of the python executable inside `.venv`.*
+
+### Adoption (Forcing the AI to use it)
+The Vault only saves tokens if the AI remembers to use it! Add this snippet to your project's `CLAUDE.md`, `.cursorrules`, or `GEMINI.md`:
+
+```markdown
+# 🧠 Agent Vault & Memory Protocol
+You are equipped with the Agent Vault MCP Server. To protect the user's token limits and eliminate hallucination, you MUST strictly adhere to the following workflow:
+
+### 1. The "Think Before You Read" Rule (Semantic Cache)
+Before you spend time reading files to understand an architecture, flow, or system (e.g., "How does auth work?"):
+* **ALWAYS** call `vault_search_questions(query)` using keywords/tags to see if a previous agent already solved this.
+* If you find a match, call `vault_search_answer(prompt)` to retrieve the pre-computed answer instantly.
+
+### 2. The "Read Before You Write" Rule (File Cache)
+Before you execute commands to read raw code files:
+* **ALWAYS** call `vault_check_file(filepath)` first. 
+* If the Vault returns a Cache Hit, trust the summary/AST and DO NOT read the raw file unless you explicitly need to edit it.
+
+### 3. The "Leave It Better Than You Found It" Rule (Updating Cache)
+Your memory is only as good as what you save. After you complete a task:
+* **Cache Modified Files:** If you edited a file, ALWAYS call `vault_cache_file(filepath, summary)` to update its digest and AST.
+* **Cache New Knowledge:** If you just spent time analyzing a complex architecture or debugging a hard issue, ALWAYS call `vault_cache_answer(prompt, response, dependencies, tags)`.
+   * *Dependencies:* You MUST provide the exact file paths your answer relies on so the Vault can auto-invalidate your answer if those files change.
+   * *Tags:* Provide 5-6 broad keyword tags (e.g., "auth, login, jwt") so future agents can easily discover your answer via `vault_search_questions`.
+```
+
+## Local vs Global Vaults
+
+By default, the MCP server creates `agent_vault.db` inside your current active project workspace. Paths are stored **relatively**. This means if you ask the agent about a file in an external project (e.g., `../Project_B/main.py`), that cross-project memory is stored locally inside your current project's database.
+
+If you prefer a **"Global Brain"** that shares all memories and file caches across every single project on your computer, simply add `AGENT_VAULT_DB_PATH` to the `env` variables in your `mcp_config.json`:
+
+```json
+"env": {
+  "PYTHONPATH": "/absolute/path/to/agent-vault-mcp",
+  "AGENT_VAULT_DB_PATH": "/absolute/path/to/.global_agent_vault.db"
+}
+```
+
+## Available MCP Tools
+- `vault_store_memory(key, content, tags)`: Save arbitrary architectural notes or debugging insights.
+- `vault_search(query, max_tokens)`: Search the vault using BM25 ranking.
+- `vault_cache_file(filepath, summary)`: Hash a file and cache its summary.
+- `vault_check_file(filepath)`: Verify a file's hash and return its cached summary + telemetry metrics.
+- `vault_stats()`: View the ROI dashboard of tokens and time saved.
+- `vault_delete_memory(key)`: Delete a stored memory.
+- `vault_evict_file(filepath)`: Evict a file from the vault cache.- `vault_cache_answer(prompt, response, dependencies, tags)`: Save an AI-generated answer linked to specific files and keywords.
+- `vault_search_questions(query, max_results)`: Keyword-search an FTS5 index to find exactly how previous cached questions were phrased based on tags.
+- `vault_search_answer(prompt)`: Retrieve a cached AI answer (automatically invalidates if dependent files have changed).
+
+## Semantic Prompt Caching (Intent Caching)
+
+In `v0.2.0`, Agent Vault introduced **Semantic Prompt Caching**. Instead of forcing AI agents to repeatedly read files and re-reason through complex architectural questions (e.g., *"How does the auth flow work?"*), agents can now cache their reasoning.
+
+### Dependency Invalidation
+To solve the classic LLM problem of "stale context hallucination," Agent Vault uses **Deterministic Dependency Invalidation**. When an agent caches an answer, it explicitly lists the files that answer depends on. 
+
+When a future agent asks the same question, the Vault calculates the real-time SHA-256 digest of those dependencies. If any file has changed, the cached answer is instantly evicted, forcing the AI to generate a fresh, accurate response.
+
+### N-to-1 Tag Mapping
+To solve the problem of "brittle exact matching" (where *"How does login work?"* misses a cache for *"How does the login work?"*), agents can assign **tags** to cached answers. 
+Agents can use `vault_search_questions("login")` to hit the FTS5 index, discover the exact phrasing of the cached question, and then fetch the answer—bypassing the need for heavy vector databases!

agent_vault_mcp-0.2.0/agent_vault/core/dsa.py

@@ -0,0 +1,71 @@
+import hashlib
+import os
+import heapq
+
+class BloomFilter:
+    def __init__(self, size=1000000, hash_count=5):
+        self.size = size
+        self.hash_count = hash_count
+        self.bit_array = [False] * size
+
+    def _hashes(self, item):
+        # Simple string-based hashing for simplicity and to avoid external dependencies
+        hashes = []
+        for i in range(self.hash_count):
+            # Using md5 for fast hashing across multiple seeds
+            h = int(hashlib.md5(f"{item}:{i}".encode('utf-8')).hexdigest(), 16)
+            hashes.append(h % self.size)
+        return hashes
+
+    def add(self, item):
+        for h in self._hashes(item):
+            self.bit_array[h] = True
+
+    def check(self, item):
+        for h in self._hashes(item):
+            if not self.bit_array[h]:
+                return False
+        return True
+
+class TokenBoundedMinHeap:
+    def __init__(self, max_tokens):
+        self.max_tokens = max_tokens
+        self.current_tokens = 0
+        self.heap = [] # stores tuples of (score, tiebreaker, tokens, item)
+        self.tiebreaker = 0
+
+    def add(self, item, score, tokens):
+        if tokens > self.max_tokens:
+            return
+
+        # We want to keep items with HIGHEST score. 
+        # Min-heap pops the SMALLEST score first.
+        # So we push (score, ...), and pop when current_tokens > max_tokens.
+        # This will remove the lowest-scored items.
+        heapq.heappush(self.heap, (score, self.tiebreaker, tokens, item))
+        self.tiebreaker += 1
+        self.current_tokens += tokens
+
+        while self.current_tokens > self.max_tokens and self.heap:
+            popped = heapq.heappop(self.heap)
+            self.current_tokens -= popped[2]
+            
+    def get_items(self):
+        # Return items sorted by score descending (highest score first)
+        sorted_items = sorted(self.heap, key=lambda x: x[0], reverse=True)
+        return [x[3] for x in sorted_items]
+
+def get_file_digest(filepath):
+    """Returns SHA-256 digest of a file, and its size, or (None, 0) if it doesn't exist."""
+    if not os.path.exists(filepath):
+        return None, 0
+    hasher = hashlib.sha256()
+    size_in_bytes = 0
+    try:
+        with open(filepath, 'rb') as f:
+            for chunk in iter(lambda: f.read(65536), b''):
+                hasher.update(chunk)
+                size_in_bytes += len(chunk)
+        return hasher.hexdigest(), size_in_bytes
+    except Exception:
+        return None, 0

agent_vault_mcp-0.2.0/agent_vault/core/storage.py

@@ -0,0 +1,343 @@
+import sqlite3
+import os
+import json
+from .dsa import BloomFilter, get_file_digest, TokenBoundedMinHeap
+
+class VaultStorage:
+    def __init__(self, db_path="vault.db"):
+        self.db_path = db_path
+        self.conn = sqlite3.connect(db_path, check_same_thread=False)
+        try:
+            os.chmod(self.db_path, 0o600)
+        except OSError:
+            pass
+        self.conn.execute("PRAGMA journal_mode=WAL;")
+        self.conn.execute("PRAGMA busy_timeout=5000;")
+        self.bloom_filter = BloomFilter()
+        self._init_db()
+
+    def _init_db(self):
+        with self.conn:
+            # FTS5 table for memory snippets
+            self.conn.execute('''
+                CREATE VIRTUAL TABLE IF NOT EXISTS memories USING fts5(
+                    key, content, tags, tokens
+                )
+            ''')
+            # Table for file cache
+            self.conn.execute('''
+                CREATE TABLE IF NOT EXISTS file_cache (
+                    filepath TEXT PRIMARY KEY,
+                    digest TEXT,
+                    summary TEXT,
+                    tokens_saved_per_hit INTEGER DEFAULT 0
+                )
+            ''')
+            # Handle schema migration for file_cache safely
+            cursor = self.conn.execute("PRAGMA table_info(file_cache)")
+            columns = [col[1] for col in cursor.fetchall()]
+            if 'tokens_saved_per_hit' not in columns:
+                self.conn.execute('ALTER TABLE file_cache ADD COLUMN tokens_saved_per_hit INTEGER DEFAULT 0')
+            
+            # Metrics table
+            self.conn.execute('''
+                CREATE TABLE IF NOT EXISTS metrics (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
+                    filepath TEXT,
+                    is_hit BOOLEAN,
+                    tokens_saved INTEGER,
+                    reason TEXT
+                )
+            ''')
+            # Handle schema migration for metrics safely
+            cursor = self.conn.execute("PRAGMA table_info(metrics)")
+            columns = [col[1] for col in cursor.fetchall()]
+            if 'reason' not in columns:
+                self.conn.execute('ALTER TABLE metrics ADD COLUMN reason TEXT')
+
+            # Prompt cache table
+            self.conn.execute('''
+                CREATE TABLE IF NOT EXISTS prompt_cache (
+                    id INTEGER PRIMARY KEY,
+                    query_hash TEXT UNIQUE,
+                    response TEXT,
+                    dependency_files TEXT
+                )
+            ''')
+            
+
+            self.conn.execute('''
+                CREATE TABLE IF NOT EXISTS prompt_cache (
+                    id INTEGER PRIMARY KEY,
+                    query_hash TEXT UNIQUE,
+                    prompt TEXT,
+                    response TEXT,
+                    dependency_files TEXT,
+                    tags TEXT
+                )
+            ''')
+            # Handle migration
+            cursor = self.conn.execute("PRAGMA table_info(prompt_cache)")
+            columns = [col[1] for col in cursor.fetchall()]
+            if 'prompt' not in columns:
+                self.conn.execute('ALTER TABLE prompt_cache ADD COLUMN prompt TEXT')
+            if 'tags' not in columns:
+                self.conn.execute('ALTER TABLE prompt_cache ADD COLUMN tags TEXT')
+                
+            self.conn.execute('''
+                CREATE VIRTUAL TABLE IF NOT EXISTS prompt_search USING fts5(
+                    prompt, tags, query_hash UNINDEXED
+                )
+            ''')
+
+        # Hydrate bloom filter with existing files
+        try:
+            cursor = self.conn.execute("SELECT filepath FROM file_cache")
+            for row in cursor:
+                self.bloom_filter.add(row[0])
+        except Exception:
+            pass
+
+    def store_memory(self, key, content, tags, tokens=None):
+        if tokens is None:
+            # simple token estimation (1 token ~= 4 chars)
+            tokens = len(content) // 4 + 1
+            
+        with self.conn:
+            # Delete if exists to update
+            self.conn.execute("DELETE FROM memories WHERE key = ?", (key,))
+            self.conn.execute(
+                "INSERT INTO memories (key, content, tags, tokens) VALUES (?, ?, ?, ?)",
+                (key, content, tags, tokens)
+            )
+
+    def search_memory(self, query, max_tokens=2000):
+        # We use BM25 which is built into FTS5 via ORDER BY rank
+        # Standard FTS5 match query
+        
+        # Sanitize query to avoid FTS syntax errors on special chars
+        safe_query = ''.join(c if c.isalnum() or c.isspace() else ' ' for c in query).strip()
+        if not safe_query:
+            return []
+            
+        try:
+            cursor = self.conn.execute('''
+                SELECT key, content, tags, tokens, rank 
+                FROM memories 
+                WHERE memories MATCH ? 
+                ORDER BY rank
+            ''', (safe_query,))
+        except sqlite3.OperationalError:
+            # fallback if query is still invalid
+            return []
+        
+        # Rank in FTS5 is more negative for better matches. 
+        # Let's negate it so higher is better for our max-heap logic.
+        heap = TokenBoundedMinHeap(max_tokens=max_tokens)
+        
+        for row in cursor:
+            key, content, tags, tokens, rank = row
+            # FTS5 rank is typically a negative value, where lower (more negative) means better.
+            # So a score of -rank means a higher positive value is better.
+            score = -rank 
+            item = {
+                "key": key,
+                "content": content,
+                "tags": tags,
+                "tokens": tokens
+            }
+            # We assume tokens is an integer
+            try:
+                tokens_int = int(tokens)
+            except (ValueError, TypeError):
+                tokens_int = len(content) // 4 + 1
+                
+            heap.add(item, score, tokens_int)
+            
+        return heap.get_items()
+
+    def close(self):
+        if self.conn:
+            self.conn.close()
+
+    def delete_memory(self, key):
+        with self.conn:
+            self.conn.execute("DELETE FROM memories WHERE key = ?", (key,))
+
+    def evict_file(self, filepath):
+        with self.conn:
+            self.conn.execute("DELETE FROM file_cache WHERE filepath = ?", (filepath,))
+
+    def cache_file(self, filepath, summary):
+        digest, raw_file_size = get_file_digest(filepath)
+        if not digest:
+            return False
+            
+        raw_tokens = raw_file_size // 4
+        summary_tokens = len(summary) // 4
+        tokens_saved_per_hit = max(0, raw_tokens - summary_tokens)
+            
+        with self.conn:
+            self.conn.execute('''
+                INSERT INTO file_cache (filepath, digest, summary, tokens_saved_per_hit)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT(filepath) DO UPDATE SET
+                    digest=excluded.digest,
+                    summary=excluded.summary,
+                    tokens_saved_per_hit=excluded.tokens_saved_per_hit
+            ''', (filepath, digest, summary, tokens_saved_per_hit))
+            
+        self.bloom_filter.add(filepath)
+        return True
+
+    def check_file(self, filepath):
+        # 1. Fast rejection
+        if not self.bloom_filter.check(filepath):
+            with self.conn:
+                self.conn.execute("INSERT INTO metrics (filepath, is_hit, tokens_saved, reason) VALUES (?, 0, 0, ?)", (filepath, "not_in_bloom"))
+            return {"cached": False, "reason": "Not in bloom filter"}
+            
+        # 2. Check digest
+        current_digest, _ = get_file_digest(filepath)
+        if not current_digest:
+             with self.conn:
+                 self.conn.execute("INSERT INTO metrics (filepath, is_hit, tokens_saved, reason) VALUES (?, 0, 0, ?)", (filepath, "not_found"))
+             return {"cached": False, "reason": "File not found or unreadable"}
+             
+        cursor = self.conn.execute("SELECT digest, summary, tokens_saved_per_hit FROM file_cache WHERE filepath = ?", (filepath,))
+        row = cursor.fetchone()
+        
+        if not row:
+            with self.conn:
+                self.conn.execute("INSERT INTO metrics (filepath, is_hit, tokens_saved, reason) VALUES (?, 0, 0, ?)", (filepath, "not_in_db"))
+            return {"cached": False, "reason": "Not in database"}
+            
+        cached_digest, summary, tokens_saved_per_hit = row
+        if current_digest == cached_digest:
+            with self.conn:
+                self.conn.execute("INSERT INTO metrics (filepath, is_hit, tokens_saved, reason) VALUES (?, 1, ?, ?)", (filepath, tokens_saved_per_hit, "hit"))
+            return {"cached": True, "summary": summary, "tokens_saved": tokens_saved_per_hit}
+        else:
+            with self.conn:
+                self.conn.execute("INSERT INTO metrics (filepath, is_hit, tokens_saved, reason) VALUES (?, 0, 0, ?)", (filepath, "digest_mismatch"))
+            return {"cached": False, "reason": "Digest mismatch"}
+
+    def get_metrics_dashboard(self):
+        cursor = self.conn.execute("SELECT COUNT(*), SUM(is_hit), SUM(tokens_saved) FROM metrics")
+        row = cursor.fetchone()
+        
+        total_checks = row[0] if row else 0
+        total_hits = row[1] if row and row[1] is not None else 0
+        total_tokens_saved = row[2] if row and row[2] is not None else 0
+        
+        hit_ratio = (total_hits / total_checks) * 100 if total_checks > 0 else 0
+        time_saved_seconds = total_tokens_saved / 50.0  # Assuming 50 tokens/sec
+        
+        if time_saved_seconds > 3600:
+            time_saved_str = f"{time_saved_seconds / 3600:.2f} hours"
+        elif time_saved_seconds > 60:
+            time_saved_str = f"{time_saved_seconds / 60:.2f} minutes"
+        else:
+            time_saved_str = f"{time_saved_seconds:.2f} seconds"
+            
+        return (
+            f"=== Vault ROI Dashboard ===\n"
+            f"Total File Checks: {total_checks}\n"
+            f"Cache Hits: {total_hits} ({hit_ratio:.1f}% hit ratio)\n"
+            f"Total Tokens Saved: {total_tokens_saved:,}\n"
+            f"Estimated Time Saved: {time_saved_str}\n"
+            f"==========================="
+        )
+
+    def cache_answer(self, prompt, response, dependencies, tags=""):
+        import hashlib
+        import json
+        query_hash = hashlib.sha256(prompt.encode('utf-8')).hexdigest()
+        deps_json = json.dumps([os.path.relpath(d) for d in dependencies])
+        with self.conn:
+            self.conn.execute("DELETE FROM prompt_cache WHERE query_hash = ?", (query_hash,))
+            self.conn.execute("DELETE FROM prompt_search WHERE query_hash = ?", (query_hash,))
+            self.conn.execute('''
+                INSERT INTO prompt_cache (query_hash, prompt, response, dependency_files, tags)
+                VALUES (?, ?, ?, ?, ?)
+            ''', (query_hash, prompt, response, deps_json, tags))
+            self.conn.execute('''
+                INSERT INTO prompt_search (prompt, tags, query_hash)
+                VALUES (?, ?, ?)
+            ''', (prompt, tags, query_hash))
+        return True
+        
+    def search_questions(self, query, max_results=5):
+        # Sanitize query
+        safe_query = ''.join(c if c.isalnum() or c.isspace() else ' ' for c in query).strip()
+        if not safe_query:
+            return "No valid search terms provided."
+        
+        # Prepare FTS exact match string format: "word1" "word2"
+        fts_query = ' '.join(f'"{word}"' for word in safe_query.split())
+            
+        try:
+            cursor = self.conn.execute('''
+                SELECT prompt, tags, rank 
+                FROM prompt_search 
+                WHERE prompt_search MATCH ? 
+                ORDER BY rank LIMIT ?
+            ''', (fts_query, max_results))
+        except Exception as e:
+            return f"Search failed: {e}"
+            
+        rows = cursor.fetchall()
+        if not rows:
+            return "No matching questions found in the cache."
+            
+        out = [f"Found {len(rows)} matching cached questions:"]
+        for i, (p, t, r) in enumerate(rows, 1):
+            out.append(f"--- Option {i} ---")
+            out.append(f"Prompt: {p}")
+            out.append(f"Tags: {t if t else 'None'}")
+            out.append("")
+        out.append("Use vault_search_answer with the exact Prompt string if one matches your intent.")
+        return "\n".join(out)
+
+
+    def search_answer(self, prompt):
+        import hashlib
+        import json
+        query_hash = hashlib.sha256(prompt.encode('utf-8')).hexdigest()
+        
+        cursor = self.conn.execute(
+            "SELECT id, response, dependency_files FROM prompt_cache WHERE query_hash = ?", 
+            (query_hash,)
+        )
+        rows = cursor.fetchall()
+        
+        for row in rows:
+            row_id, response, deps_json = row
+            dependencies = json.loads(deps_json)
+            
+            is_valid = True
+            for filepath in dependencies:
+                # Get current digest from disk
+                current_digest, _ = get_file_digest(filepath)
+                if not current_digest:
+                    is_valid = False
+                    break
+                    
+                # Get cached digest from file_cache
+                c = self.conn.execute("SELECT digest FROM file_cache WHERE filepath = ?", (filepath,))
+                cached_row = c.fetchone()
+                
+                if not cached_row or cached_row[0] != current_digest:
+                    is_valid = False
+                    break
+                    
+            if is_valid:
+                return response
+            else:
+                # Evict stale cache entry
+                with self.conn:
+                    self.conn.execute("DELETE FROM prompt_cache WHERE id = ?", (row_id,))
+                    
+        return None
+

agent_vault_mcp-0.2.0/agent_vault/server.py

@@ -0,0 +1,144 @@
+from mcp.server.mcpserver import MCPServer
+from .core.storage import VaultStorage
+import os
+
+import sys
+
+# Initialize FastMCP server
+mcp = MCPServer("AgentVault")
+
+# Initialize storage
+# Using an environment variable or default local db
+db_path = os.environ.get("AGENT_VAULT_DB_PATH", "agent_vault.db")
+try:
+    storage = VaultStorage(db_path)
+except Exception as e:
+    print(f"Failed to initialize VaultStorage at {db_path}: {e}", file=sys.stderr)
+    sys.exit(1)
+
+@mcp.tool()
+def vault_store_memory(key: str, content: str, tags: str) -> str:
+    """Store a snippet of memory in the vault with FTS5 indexing.
+    
+    Args:
+        key: A unique identifier for this memory.
+        content: The actual knowledge or code snippet.
+        tags: Comma separated tags for the memory.
+    """
+    storage.store_memory(key, content, tags)
+    return f"Memory '{key}' stored successfully."
+
+@mcp.tool()
+def vault_search(query: str, max_tokens: int = 2000) -> str:
+    """Search the vault using BM25, bounded by a token limit.
+    
+    Args:
+        query: The search query.
+        max_tokens: The maximum number of tokens to return to fit in context.
+    """
+    max_tokens = max(50, max_tokens)
+    results = storage.search_memory(query, max_tokens=max_tokens)
+    if not results:
+        return "No memories found matching the query."
+        
+    output = [f"Found {len(results)} results within {max_tokens} tokens:\n"]
+    for i, res in enumerate(results, 1):
+        output.append(f"--- Result {i} (Key: {res['key']}, Tags: {res['tags']}) ---")
+        output.append(res['content'])
+        output.append("")
+        
+    return "\n".join(output)
+
+@mcp.tool()
+def vault_cache_file(filepath: str, summary: str) -> str:
+    """Digest a file (SHA-256) and cache its summary/AST.
+    
+    Args:
+        filepath: Absolute path to the file.
+        summary: The summary or AST of the file.
+    """
+    filepath = os.path.relpath(filepath)
+    success = storage.cache_file(filepath, summary)
+    if success:
+        return f"File '{filepath}' cached successfully."
+    else:
+        return f"Failed to cache '{filepath}'. Does it exist?"
+
+@mcp.tool()
+def vault_check_file(filepath: str) -> str:
+    """Check if a file has been modified since it was last cached.
+    Uses O(1) Bloom Filter for fast rejection, then SHA-256 for exact match.
+    
+    Args:
+        filepath: Absolute path to the file.
+    """
+    filepath = os.path.relpath(filepath)
+    result = storage.check_file(filepath)
+    if result["cached"]:
+        tokens_saved = result.get("tokens_saved", 0)
+        telemetry = f"\n[Vault telemetry: Saved {tokens_saved:,} tokens by skipping raw file read]"
+        return f"File '{filepath}' is unchanged. Summary:\n{result['summary']}{telemetry}"
+    else:
+        return f"File '{filepath}' needs analysis. Reason: {result['reason']}"
+
+@mcp.tool()
+def vault_stats() -> str:
+    """Get the Vault ROI Dashboard showing all-time tokens and time saved."""
+    return storage.get_metrics_dashboard()
+
+@mcp.tool()
+def vault_delete_memory(key: str) -> str:
+    """Delete a memory from the vault by key."""
+    storage.delete_memory(key)
+    return f"Memory '{key}' deleted successfully."
+
+@mcp.tool()
+def vault_evict_file(filepath: str) -> str:
+    """Evict a file from the vault cache."""
+    filepath = os.path.relpath(filepath)
+    storage.evict_file(filepath)
+    return f"File '{filepath}' evicted successfully."
+
+@mcp.tool()
+def vault_cache_answer(prompt: str, response: str, dependencies: list[str], tags: str = "") -> str:
+    """Cache an AI response with its file dependencies and tags.
+    
+    Args:
+        prompt: The exact prompt/question.
+        response: The AI's generated response.
+        dependencies: A list of absolute or relative file paths this response depends on.
+        tags: Comma separated tags (e.g. 'auth, login, jwt') to help future agents find this prompt.
+    """
+    storage.cache_answer(prompt, response, dependencies, tags)
+    return "Answer cached successfully."
+
+@mcp.tool()
+def vault_search_questions(query: str, max_results: int = 5) -> str:
+    """Discover cached questions using a keyword search.
+    Returns a list of exact cached prompts. Once you find a match, use vault_search_answer with the exact prompt.
+    
+    Args:
+        query: The semantic intent or keywords (e.g., 'auth login flow').
+        max_results: Max number of question options to return.
+    """
+    return storage.search_questions(query, max_results)
+
+@mcp.tool()
+def vault_search_answer(prompt: str) -> str:
+    """Search for a cached AI response based on a prompt.
+    Checks if dependency files have changed since caching.
+    
+    Args:
+        prompt: The user's prompt.
+    """
+    result = storage.search_answer(prompt)
+    if result:
+        return f"Cached Answer:\n{result}"
+    else:
+        return "No valid cached answer found."
+
+def main():
+    mcp.run()
+
+if __name__ == "__main__":
+    main()

agent_vault_mcp-0.2.0/agent_vault_mcp.egg-info/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: agent-vault-mcp
+Version: 0.2.0
+Summary: DSA-Optimized AI Knowledge Bank MCP Server
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp<3,>=2
+
+# Agent Vault MCP
+
+A blazing-fast, token-efficient AI Knowledge Bank and Memory Server built on the **Model Context Protocol (MCP)**. 
+
+Agent Vault is designed to give AI coding agents (like Claude Code, Antigravity, and Cursor) persistent, cross-session memory without blowing up token limits. It acts as an intelligent file digest cache and semantic knowledge base.
+
+## Overview
+AI agents typically start every session with amnesia, forcing them to re-read thousands of lines of code. Agent Vault solves this using a **Two-Step Funnel**:
+1. **Discovery**: The agent searches the Vault to find out *which* files matter.
+2. **Execution**: The agent reads only the raw code of those specific files, edits them, and updates the vault.
+
+When the agent wants to check a file, the Vault hashes it (SHA-256). If it hasn't changed, the Vault instantly returns a cached AST/summary instead of making the agent read the entire file.
+
+## Features
+- **$O(1)$ Fast Rejection**: Uses Bloom Filters to instantly know if a file is unindexed.
+- **Token-Bounded MinHeap**: Ranks the best context snippets and strictly cuts off when the maximum token limit is reached, protecting the context window.
+- **SQLite FTS5 (BM25)**: Fast lexical and semantic search for symbols, errors, and flows.
+- **ROI Telemetry**: Natively calculates and tracks how many tokens and hours of inference time are saved by skipping raw file reads.
+- **100% Portable**: Caches are stored using relative paths, meaning you can move or rename your project folder without breaking the vault.
+
+## Dependencies
+- Python 3.10+
+- `mcp` (Official Model Context Protocol SDK, `mcp>=2,<3`)
+- Standard library components (`sqlite3`, `hashlib`, `heapq`)
+
+## Installation
+
+### Option 1: Global Python (3.10+)
+```bash
+# Clone or navigate to the repository
+cd agent-vault-mcp
+
+# Install the package
+pip install -e .
+```
+
+### Option 2: Using `uv` (Virtual Environment)
+```bash
+uv venv --python 3.12
+.venv\Scripts\activate  # On Windows
+uv pip install -e .
+```
+
+## How to use with Antigravity / Claude Code
+
+To add this to an MCP client like Antigravity, add the following to your `mcp_config.json` (e.g., `~/.gemini/config/mcp_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-vault": {
+      "command": "python",
+      "args": ["-m", "agent_vault.server"],
+      "env": {
+        "PYTHONPATH": "/absolute/path/to/agent-vault-mcp"
+      }
+    }
+  }
+}
+```
+*Note: If you used a virtual environment, change `"command": "python"` to the absolute path of the python executable inside `.venv`.*
+
+### Adoption (Forcing the AI to use it)
+The Vault only saves tokens if the AI remembers to use it! Add this snippet to your project's `CLAUDE.md`, `.cursorrules`, or `GEMINI.md`:
+
+```markdown
+# 🧠 Agent Vault & Memory Protocol
+You are equipped with the Agent Vault MCP Server. To protect the user's token limits and eliminate hallucination, you MUST strictly adhere to the following workflow:
+
+### 1. The "Think Before You Read" Rule (Semantic Cache)
+Before you spend time reading files to understand an architecture, flow, or system (e.g., "How does auth work?"):
+* **ALWAYS** call `vault_search_questions(query)` using keywords/tags to see if a previous agent already solved this.
+* If you find a match, call `vault_search_answer(prompt)` to retrieve the pre-computed answer instantly.
+
+### 2. The "Read Before You Write" Rule (File Cache)
+Before you execute commands to read raw code files:
+* **ALWAYS** call `vault_check_file(filepath)` first. 
+* If the Vault returns a Cache Hit, trust the summary/AST and DO NOT read the raw file unless you explicitly need to edit it.
+
+### 3. The "Leave It Better Than You Found It" Rule (Updating Cache)
+Your memory is only as good as what you save. After you complete a task:
+* **Cache Modified Files:** If you edited a file, ALWAYS call `vault_cache_file(filepath, summary)` to update its digest and AST.
+* **Cache New Knowledge:** If you just spent time analyzing a complex architecture or debugging a hard issue, ALWAYS call `vault_cache_answer(prompt, response, dependencies, tags)`.
+   * *Dependencies:* You MUST provide the exact file paths your answer relies on so the Vault can auto-invalidate your answer if those files change.
+   * *Tags:* Provide 5-6 broad keyword tags (e.g., "auth, login, jwt") so future agents can easily discover your answer via `vault_search_questions`.
+```
+
+## Local vs Global Vaults
+
+By default, the MCP server creates `agent_vault.db` inside your current active project workspace. Paths are stored **relatively**. This means if you ask the agent about a file in an external project (e.g., `../Project_B/main.py`), that cross-project memory is stored locally inside your current project's database.
+
+If you prefer a **"Global Brain"** that shares all memories and file caches across every single project on your computer, simply add `AGENT_VAULT_DB_PATH` to the `env` variables in your `mcp_config.json`:
+
+```json
+"env": {
+  "PYTHONPATH": "/absolute/path/to/agent-vault-mcp",
+  "AGENT_VAULT_DB_PATH": "/absolute/path/to/.global_agent_vault.db"
+}
+```
+
+## Available MCP Tools
+- `vault_store_memory(key, content, tags)`: Save arbitrary architectural notes or debugging insights.
+- `vault_search(query, max_tokens)`: Search the vault using BM25 ranking.
+- `vault_cache_file(filepath, summary)`: Hash a file and cache its summary.
+- `vault_check_file(filepath)`: Verify a file's hash and return its cached summary + telemetry metrics.
+- `vault_stats()`: View the ROI dashboard of tokens and time saved.
+- `vault_delete_memory(key)`: Delete a stored memory.
+- `vault_evict_file(filepath)`: Evict a file from the vault cache.- `vault_cache_answer(prompt, response, dependencies, tags)`: Save an AI-generated answer linked to specific files and keywords.
+- `vault_search_questions(query, max_results)`: Keyword-search an FTS5 index to find exactly how previous cached questions were phrased based on tags.
+- `vault_search_answer(prompt)`: Retrieve a cached AI answer (automatically invalidates if dependent files have changed).
+
+## Semantic Prompt Caching (Intent Caching)
+
+In `v0.2.0`, Agent Vault introduced **Semantic Prompt Caching**. Instead of forcing AI agents to repeatedly read files and re-reason through complex architectural questions (e.g., *"How does the auth flow work?"*), agents can now cache their reasoning.
+
+### Dependency Invalidation
+To solve the classic LLM problem of "stale context hallucination," Agent Vault uses **Deterministic Dependency Invalidation**. When an agent caches an answer, it explicitly lists the files that answer depends on. 
+
+When a future agent asks the same question, the Vault calculates the real-time SHA-256 digest of those dependencies. If any file has changed, the cached answer is instantly evicted, forcing the AI to generate a fresh, accurate response.
+
+### N-to-1 Tag Mapping
+To solve the problem of "brittle exact matching" (where *"How does login work?"* misses a cache for *"How does the login work?"*), agents can assign **tags** to cached answers. 
+Agents can use `vault_search_questions("login")` to hit the FTS5 index, discover the exact phrasing of the cached question, and then fetch the answer—bypassing the need for heavy vector databases!

agent_vault_mcp-0.2.0/agent_vault_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+agent_vault/__init__.py
+agent_vault/server.py
+agent_vault/core/__init__.py
+agent_vault/core/dsa.py
+agent_vault/core/storage.py
+agent_vault_mcp.egg-info/PKG-INFO
+agent_vault_mcp.egg-info/SOURCES.txt
+agent_vault_mcp.egg-info/dependency_links.txt
+agent_vault_mcp.egg-info/entry_points.txt
+agent_vault_mcp.egg-info/requires.txt
+agent_vault_mcp.egg-info/top_level.txt
+tests/test_prompt_cache.py

agent_vault_mcp-0.2.0/agent_vault_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_vault_mcp-0.2.0/agent_vault_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-vault = agent_vault.server:main

agent_vault_mcp-0.2.0/agent_vault_mcp.egg-info/requires.txt

@@ -0,0 +1 @@
+mcp<3,>=2

agent_vault_mcp-0.2.0/agent_vault_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+agent_vault

agent_vault_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,12 @@
+[project]
+name = "agent-vault-mcp"
+version = "0.2.0"
+description = "DSA-Optimized AI Knowledge Bank MCP Server"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=2,<3",
+]
+
+[project.scripts]
+agent-vault = "agent_vault.server:main"

agent_vault_mcp-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_vault_mcp-0.2.0/tests/test_prompt_cache.py

@@ -0,0 +1,53 @@
+import os
+import time
+from agent_vault.core.storage import VaultStorage
+
+def run_tests():
+    db_path = "test_vault.db"
+    if os.path.exists(db_path):
+        os.remove(db_path)
+        
+    storage = VaultStorage(db_path)
+    
+    # Create a dummy dependency file
+    with open("dummy_dep.py", "w") as f:
+        f.write("print('hello')\n")
+        
+    # We must cache the file in file_cache first, because search_answer relies on file_cache having the digest
+    storage.cache_file("dummy_dep.py", "A dummy file")
+        
+    prompt = "How does the dummy work?"
+    response = "It prints hello."
+    deps = ["dummy_dep.py"]
+    
+    # Cache the answer
+    storage.cache_answer(prompt, response, deps)
+    print("Answer cached.")
+    
+    # Search the answer
+    res = storage.search_answer(prompt)
+    if res == response:
+        print("Hit! (Expected)")
+    else:
+        print("Miss! (Unexpected)")
+        
+    # Modify the dependency file
+    with open("dummy_dep.py", "a") as f:
+        f.write("print('world')\n")
+        
+    # Search the answer again
+    res = storage.search_answer(prompt)
+    if res is None:
+        print("Miss! (Expected, file changed)")
+    else:
+        print(f"Hit! (Unexpected, returned {res})")
+        
+    # Clean up
+    storage.close()
+    if os.path.exists(db_path):
+        os.remove(db_path)
+    if os.path.exists("dummy_dep.py"):
+        os.remove("dummy_dep.py")
+
+if __name__ == "__main__":
+    run_tests()