indra_db_mcp 0.1.24 → 0.2.2

package/README.md

@@ -1,190 +1,163 @@
 # indra_db_mcp
 
-> **Think out loud. Remember what matters. Watch understanding evolve.**
+> **Persistent memory for AI reasoning and decisions.**
 
-An MCP (Model Context Protocol) server that gives AI models a place to externalize their thinking. Built on [indra_db](https://github.com/moonstripe/indra_db) — a content-addressed graph database for versioned thoughts.
+An MCP server that gives AI agents memory that persists across sessions. Built on [indra_db](https://github.com/moonstripe/indra_db) — a git-like database for versioned thoughts.
 
-## Why This Exists
+## The Problem
 
-Most AI interactions are ephemeral. Insights evaporate. Reasoning chains vanish. Good ideas get rediscovered instead of built upon.
+AI agents start fresh every session. Yesterday's insights evaporate. Decisions get re-made. Reasoning chains vanish.
 
-**indra_db_mcp** changes that by giving models (and humans) a shared space to:
+**indra_db_mcp** changes that by giving agents:
 
-- 🧠 **Capture thoughts** as they emerge during reasoning
-- 🔗 **Connect ideas** into a web of understanding  
-- 🔮 **Search by meaning** not just keywords
-- 🌿 **Branch and explore** alternative lines of thinking
-- 📜 **Track evolution** of understanding over time
-
-It's git for thoughts. Version-controlled thinking. A knowledge graph that grows with every conversation.
+- 🧠 **Persistent memory** — Record reasoning that survives session boundaries
+- 🔍 **Semantic search** — Find past decisions by meaning, not keywords
+- 🌿 **Branching** — Explore alternatives without losing the main thread
+- 📜 **History** — See how understanding evolved over time
 
 ## Quick Start
 
-### Prerequisites
+### Install
+
+No installation required — use `bunx` for automatic updates:
+
+```bash
+bunx -y indra_db_mcp@latest
+```
+
+Or install globally:
+```bash
+bun add -g indra_db_mcp
+```
+
+### Configure Your Agent
 
-- [Bun](https://bun.sh/) runtime (v1.0+)
-- [Rust/Cargo](https://rustup.rs/) (for auto-installing indra_db CLI)
+**Claude Code** — Add to your project's `CLAUDE.md`:
 
-### Usage with MCP Clients
+```markdown
+@import node_modules/indra_db_mcp/INDRA_INSTRUCTIONS.md
+```
 
-The simplest way to use this server is via `bunx`:
+**Claude Desktop** — Add to `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "indra": {
-      "command": ["bunx", "-y", "indra_db_mcp"],
-      "type": "local"
+      "command": "bunx",
+      "args": ["-y", "indra_db_mcp@latest"]
     }
   }
 }
 ```
 
-### Enabling Proactive Use
+**OpenCode** — Add to `~/.config/opencode/opencode.json`:
 
-Models won't automatically use Indra unless instructed. Add the bundled instructions file to your config:
-
-**OpenCode** (`~/.config/opencode/opencode.json` or project `opencode.json`):
 ```json
 {
-  "instructions": ["node_modules/indra_db_mcp/INDRA_INSTRUCTIONS.md"]
+  "mcp": {
+    "indra": {
+      "command": ["bunx", "-y", "indra_db_mcp@latest"],
+      "type": "local"
+    }
+  },
+  "instructions": ["~/.config/opencode/instructions/indra.md"]
 }
 ```
 
-**Claude Code** (project `CLAUDE.md` or global `~/.claude/CLAUDE.md`):
-```markdown
-<!-- Include Indra instructions -->
-@import node_modules/indra_db_mcp/INDRA_INSTRUCTIONS.md
+Then copy INDRA_INSTRUCTIONS.md:
+```bash
+mkdir -p ~/.config/opencode/instructions
+curl -o ~/.config/opencode/instructions/indra.md \
+  https://raw.githubusercontent.com/moonstripe/indra_db_mcp/main/INDRA_INSTRUCTIONS.md
 ```
 
-Or copy `INDRA_INSTRUCTIONS.md` to your project and reference it directly.
-
-Or with a custom database path:
+**Generic MCP Client:**
 
 ```json
 {
   "mcpServers": {
     "indra": {
-      "command": ["bunx", "-y", "indra_db_mcp"],
-      "environment": {
-        "INDRA_DB_PATH": "~/.indra"
-      },
-      "type": "local"
+      "command": "bunx",
+      "args": ["-y", "indra_db_mcp@latest"],
+      "env": {
+        "INDRA_DB_PATH": "./.indra"
+      }
     }
   }
 }
 ```
 
-### Manual Installation
-
-```bash
-# Install globally
-bun add -g indra_db_mcp
-
-# Or clone and run locally
-git clone https://github.com/moonstripe/indra_db_mcp
-cd indra_db_mcp
-bun install
-bun start
-
-# The indra CLI will auto-install on first run via cargo
-```
-
-### Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `INDRA_DB_PATH` | Path to database file | `./.indra` (hidden file) |
-
-When `INDRA_DB_PATH` is set, uses that path (supports `~` for home directory).
-When unset, creates a hidden `.indra` file in the current working directory.
-
-## Available Tools
+## Tools
 
-### 🧠 Thought Capture
+| Tool | Purpose |
+|------|---------|
+| `indra_remember` | Record reasoning, decisions, and insights |
+| `indra_search` | Find past reasoning by meaning (or `"*"` for all) |
+| `indra_status` | Check current branch and entry count |
+| `indra_branch` | Create, switch, or list branches |
+| `indra_experiment` | Quick sandbox for exploring alternatives |
+| `indra_history` | See how reasoning evolved |
+| `indra_diff` | Compare two points in history |
 
-| Tool | Description |
-|------|-------------|
-| `remember` | Capture a thought with optional ID. Embeddings auto-generated for semantic search. |
-| `recall` | Retrieve a specific thought by ID. |
-| `revise` | Update a thought while preserving history. |
-| `forget` | Remove from current state (preserved in history). |
-| `list_thoughts` | See all thoughts in the graph. |
+## Example Usage
 
-### 🔗 Relationship Building
-
-| Tool | Description |
-|------|-------------|
-| `connect` | Create typed relationship between thoughts. |
-| `disconnect` | Remove a relationship. |
-| `explore` | Traverse connections from a thought. |
-
-**Built-in relationship types:**
-- `supports` — evidence/backing
-- `contradicts` — conflicts with
-- `derives_from` — evolved from
-- `part_of` — component of larger idea
-- `causes` — leads to
-- `precedes` — temporal ordering
-- `similar_to` — related concepts
-- `relates_to` — general connection
-
-### 🔮 Semantic Search
-
-| Tool | Description |
-|------|-------------|
-| `search` | Find thoughts by meaning using vector embeddings. |
-
-### 📜 Version Control
-
-| Tool | Description |
-|------|-------------|
-| `checkpoint` | Commit current state with a message. |
-| `history` | View commit log showing evolution. |
-| `branch` | Create new line of exploration. |
-| `switch_branch` | Move between branches. |
-| `list_branches` | See all branches. |
-| `compare` | Diff between states. |
-| `status` | Current database overview. |
-
-## Example Session
-
-Here's how an AI might use this during reasoning:
+An agent might use Indra like this:
 
 ```
-User: Help me think through whether to use microservices or a monolith for my startup.
-
-AI: Let me capture my initial thoughts on this decision...
-
-[Uses remember] "The microservices vs monolith decision depends heavily on team size, 
-expected scale, and operational maturity"
+User: Should I use PostgreSQL or MongoDB for my e-commerce app?
+
+Agent thinking:
+  → indra_search({ query: "database recommendations" })
+  → Found: Previously recommended PostgreSQL for relational data with transactions
+  
+  → Making recommendation based on past reasoning + current context
+  
+  → indra_remember({ 
+      content: "Recommended PostgreSQL for e-commerce app. User has relational product 
+               catalog, needs transactions for orders. Consistent with past guidance.",
+      id: "ecommerce-db-decision"
+    })
+```
 
-[Uses remember] "Startups typically benefit from monoliths initially - faster iteration, 
-simpler deployment, easier debugging"
+Later:
 
-[Uses remember] "Microservices add operational overhead: service discovery, distributed 
-tracing, network latency, deployment complexity"
+```
+User: Why did you recommend PostgreSQL?
 
-[Uses connect] "monolith-benefits" --[supports]--> "startup-recommendation"
-[Uses connect] "microservices-overhead" --[contradicts]--> "premature-microservices"
+Agent:
+  → indra_search({ query: "ecommerce database" })
+  → Found the reasoning from the previous session
+  → Can explain the decision with full context
+```
 
-[Uses checkpoint] "Initial analysis of architecture decision"
+### Branching for Exploration
 
-Let me explore an alternative perspective...
+```
+Agent: Let me explore an alternative approach...
+
+  → indra_experiment({ name: "try-nosql-approach" })
+  
+  [Explores MongoDB path, records reasoning]
+  
+  → indra_diff({ from: "main" })  // Compare with main reasoning
+  
+  → indra_branch({ action: "switch", name: "main" })  // Back to main
+```
 
-[Uses branch] "microservices-case"
-[Uses switch_branch] "microservices-case"
+## Environment Variables
 
-[Uses remember] "If expecting rapid team growth, microservices enable independent 
-team ownership and deployment"
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `INDRA_DB_PATH` | Path to database file | `./.indra` |
+| `INDRA_API_URL` | API for sync (optional) | `https://api.indradb.net` |
 
-[Uses search] "team scaling" 
-// Finds related thoughts about team dynamics
+## How It Works
 
-[Uses switch_branch] "main"
-[Uses compare] "main" vs "microservices-case"
-// Shows what each branch explored
-```
+1. **Content-addressed storage** — Every entry is hashed. Identity comes from content.
+2. **Local embeddings** — Uses `sentence-transformers/all-MiniLM-L6-v2` for semantic search.
+3. **Git-like versioning** — Commits create snapshots. Branches enable parallel exploration.
+4. **Single file** — Everything in one `.indra` file. Easy to backup and share.
 
 ## Architecture
 
@@ -196,7 +169,7 @@ team ownership and deployment"
 ┌─────────────────────────▼───────────────────────────────┐
 │                   indra_db_mcp (Bun)                     │
 │  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐  │
-│  │   MCP SDK   │  │ IndraClient  │  │  Type Safety  │  │
+│  │   MCP SDK   │  │ IndraClient  │  │ Auto-sync     │  │
 │  └─────────────┘  └──────┬───────┘  └───────────────┘  │
 └──────────────────────────┼──────────────────────────────┘
                            │ CLI subprocess (JSON)
@@ -205,51 +178,19 @@ team ownership and deployment"
 │  ┌─────────────┐  ┌──────────────┐  ┌───────────────┐  │
 │  │ Graph Store │  │  Embeddings  │  │  Git-like VCS │  │
 │  └─────────────┘  └──────────────┘  └───────────────┘  │
-└─────────────────────────────────────────────────────────┘
-                           │
-┌──────────────────────────▼──────────────────────────────┐
-│              thoughts.indra (Single File)                │
-│  Content-addressed objects, BLAKE3 hashes, zstd compressed│
 └─────────────────────────────────────────────────────────┘
 ```
 
-## Development
+## Visualize on IndraDB
 
-```bash
-# Run with watch mode
-bun run dev
+Push to [IndraDB](https://indradb.net) for 3D visualization and analytics:
 
-# Type check
-bun run typecheck
-
-# Run tests
-bun test
+```bash
+indra login
+indra remote add origin username/my-memory
+indra push origin
 ```
 
-## How It Works
-
-1. **Content Addressing**: Every thought is hashed (BLAKE3). Identity comes from content.
-
-2. **Embeddings**: Using `sentence-transformers/all-MiniLM-L6-v2` locally via HuggingFace. 
-   Thoughts are embedded on creation for semantic search.
-
-3. **Graph Structure**: Thoughts are nodes, relationships are typed/weighted edges.
-   Edges "float" to latest node versions.
-
-4. **Version Control**: Git-like commits create snapshots. Branches enable parallel exploration.
-   Full history preserved — nothing truly deleted.
-
-5. **Single File**: Everything stored in one `.indra` file. Easy to backup, share, version.
-
-## Philosophical Note
-
-This project is named after [Indra's Net](https://en.wikipedia.org/wiki/Indra%27s_net) — 
-a Buddhist metaphor where reality is a vast net of jewels, each reflecting all others.
-
-Your thoughts are like those jewels. Each one reflects and connects to others. 
-The web of connections *is* your understanding. This tool makes that web visible, 
-versionable, and searchable.
-
 ## License
 
 MIT
@@ -257,5 +198,5 @@ MIT
 ## Related
 
 - [indra_db](https://github.com/moonstripe/indra_db) — The underlying Rust database
+- [IndraDB](https://indradb.net) — Web platform for visualization
 - [MCP Specification](https://modelcontextprotocol.io/) — Model Context Protocol docs
-- [indranet](https://github.com/moonstripe/indranet) — Online viewing tool (coming soon)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "indra_db_mcp",
-  "version": "0.1.24",
+  "version": "0.2.2",
   "description": "MCP server for indra_db - a content-addressed graph database for versioned thoughts",
   "type": "module",
   "bin": {

package/src/e2e.test.ts

@@ -166,6 +166,52 @@ describe("End-to-End: Real MCP Usage Patterns", () => {
   // Stress Tests
   // ==========================================================================
 
+  test("stress: concurrent writes should not corrupt database (issue #2)", async () => {
+    const client = new IndraClient({ databasePath: dbPath });
+    
+    // Fire off 7+ writes concurrently (the exact pattern that caused corruption)
+    const writes = Array.from({ length: 10 }, (_, i) =>
+      client.createThought(`Concurrent note ${i}: rapid fire save`, { id: `concurrent-${i}` })
+    );
+    
+    // All should succeed without corruption
+    const results = await Promise.all(writes);
+    expect(results.length).toBe(10);
+    
+    // Verify all notes persisted correctly
+    const newClient = new IndraClient({ databasePath: dbPath });
+    const all = await newClient.listThoughts();
+    expect(all.count).toBe(10);
+    
+    // Verify each one is readable
+    for (let i = 0; i < 10; i++) {
+      const thought = await newClient.getThought(`concurrent-${i}`);
+      expect(thought.content).toContain(`Concurrent note ${i}`);
+    }
+  });
+
+  test("stress: concurrent writes with interleaved reads (issue #2)", async () => {
+    const client = new IndraClient({ databasePath: dbPath });
+    
+    // Interleave writes and reads concurrently
+    const operations = [];
+    for (let i = 0; i < 5; i++) {
+      operations.push(client.createThought(`Interleaved ${i}`, { id: `interleaved-${i}` }));
+      operations.push(client.listThoughts());
+      operations.push(client.search("interleaved", 10));
+    }
+    
+    // None should throw corruption errors
+    const results = await Promise.allSettled(operations);
+    const failures = results.filter(r => r.status === 'rejected');
+    expect(failures.length).toBe(0);
+    
+    // Verify final state
+    const newClient = new IndraClient({ databasePath: dbPath });
+    const all = await newClient.listThoughts();
+    expect(all.count).toBe(5);
+  });
+
   test("stress: many notes across many sessions", async () => {
     const noteCount = 50;
     

package/src/index.ts

@@ -1,15 +1,10 @@
 #!/usr/bin/env bun
 /**
- * indra_db MCP Server - Simplified API
+ * indra_db MCP Server
  * 
- * A Model Context Protocol server for managing the user's personal notes.
- * 
- * DESIGN PRINCIPLES:
- * 1. Minimal tools - each tool does ONE thing well
- * 2. Auto-commit - every mutation persists immediately
- * 3. Auto-sync - pull before search, push after remember
- * 4. Self-contained - no tool depends on another being called first
- * 5. Clear purpose - tool names match what users would say
+ * Persistent memory for your reasoning process.
+ * Track how your understanding evolves, why you made decisions,
+ * and explore alternative approaches through branching.
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -24,7 +19,7 @@ import { IndraError } from "./types.js";
 
 const server = new McpServer({
   name: "indra_db",
-  version: "0.1.24",
+  version: "0.2.2",
 });
 
 const client = new IndraClient();
@@ -38,28 +33,15 @@ interface SyncResult {
   warning?: string;
 }
 
-/**
- * Check if we have authentication configured.
- * Auth is needed for:
- * - Pushing to any base (you need to be logged in to write)
- * - Pulling from private bases
- * 
- * Authentication can come from:
- * - INDRA_API_KEY env var (legacy API key)
- * - OAuth credentials file (from `indra login`)
- */
 function hasAuth(): boolean {
-  // Check for legacy API key
   if (process.env.INDRA_API_KEY) {
     return true;
   }
   
-  // Check for OAuth credentials file
   const { existsSync } = require("fs");
   const { homedir } = require("os");
   const { join } = require("path");
   
-  // Check both possible credential locations
   const credentialsPaths = [
     join(homedir(), "Library", "Application Support", "indra", "credentials.json"),
     join(homedir(), ".config", "indra", "credentials.json"),
@@ -74,40 +56,25 @@ function hasAuth(): boolean {
   return false;
 }
 
-/**
- * Attempt to pull from remote before read operations.
- * Uses hash comparison for fast merge (ORT-style).
- * Returns warning message if sync failed, but never throws.
- * 
- * Pull behavior:
- * - Public bases: works without auth
- * - Private bases: requires INDRA_API_KEY
- * - No remote configured: silently skip (local-only mode is fine)
- */
 async function tryPullSync(): Promise<SyncResult> {
   try {
-    // Check if remote is configured
     const remotes = await client.remoteList();
     if (remotes.count === 0) {
-      return { synced: false }; // No remote, that's fine - local only mode
+      return { synced: false };
     }
     
     const result = await client.pull();
     if (result.status === "ok") {
       return { synced: true };
     } else if (result.status === "pending") {
-      // API not connected yet - this is expected during development
       return { synced: false };
     } else if (result.message?.includes("Not found")) {
-      // Remote doesn't exist yet or is private without auth - that's ok for reads
       return { synced: false };
     } else {
       return { synced: false, warning: `Sync: ${result.message}` };
     }
   } catch (error) {
-    // Network error or other issue - don't block the operation
     const msg = error instanceof Error ? error.message : String(error);
-    // Only warn if it's not a "no remote" or "not found" error
     if (!msg.includes("not found") && !msg.includes("No remote") && !msg.includes("Not found")) {
       return { synced: false, warning: `Sync unavailable: ${msg}` };
     }
@@ -115,27 +82,14 @@ async function tryPullSync(): Promise<SyncResult> {
   }
 }
 
-/**
- * Attempt to push to remote after write operations.
- * Returns warning message if sync failed, but never throws.
- * 
- * Push behavior:
- * - Always requires auth (you need to be logged in to write)
- * - No remote configured: silently skip
- * - No auth: skip silently (user is in local-only mode)
- */
 async function tryPushSync(): Promise<SyncResult> {
   try {
-    // Check if remote is configured
     const remotes = await client.remoteList();
     if (remotes.count === 0) {
-      return { synced: false }; // No remote, that's fine - local only mode
+      return { synced: false };
     }
     
-    // Check if we have auth - push always requires it
     if (!hasAuth()) {
-      // No auth, but that's fine - user is working locally
-      // They can push later with `indra login` + `indra push`
       return { synced: false };
     }
     
@@ -143,13 +97,11 @@ async function tryPushSync(): Promise<SyncResult> {
     if (result.status === "ok") {
       return { synced: true };
     } else if (result.status === "pending") {
-      // API not connected yet - this is expected during development
       return { synced: false };
     } else {
       return { synced: false, warning: `Sync: ${result.message}` };
     }
   } catch (error) {
-    // Network error or other issue - don't block the operation
     const msg = error instanceof Error ? error.message : String(error);
     if (!msg.includes("not found") && !msg.includes("No remote")) {
       return { synced: false, warning: `Sync unavailable: ${msg}` };
@@ -159,7 +111,7 @@ async function tryPushSync(): Promise<SyncResult> {
 }
 
 // ============================================================================
-// Helper: Format responses for LLM consumption
+// Helper: Format responses
 // ============================================================================
 
 function formatSuccess(
@@ -201,42 +153,44 @@ function formatError(error: unknown): { content: Array<{ type: "text"; text: str
 }
 
 // ============================================================================
-// TOOL: indra_remember - Save or update notes
+// TOOL: indra_remember - Document your reasoning
 // ============================================================================
 
 server.tool(
   "indra_remember",
-  `Save information to improve future conversations.
+  `Capture your reasoning — the WHY behind decisions.
+
+THIS IS YOUR PRIMARY TOOL. Use it liberally.
 
-Every note you save makes you more helpful next time:
-- User preferences → Better recommendations
-- Context/situation → More relevant answers  
-- Your recommendations → Continuity of advice
+CALL THIS WHEN you:
+- Make a recommendation (record WHY you chose this approach)
+- Change direction (capture WHAT SHIFTED your thinking)
+- Reach a conclusion (preserve the reasoning chain)
+- Learn something that changes how you'd approach similar problems
+- Complete a task (document what worked and why)
 
-The user set up this system because they WANT you to remember things.
-Saving notes IS the service - don't ask permission, just do it.
+WHAT TO RECORD:
+- "Chose X because A, B, C" — not just "using X"
+- "Shifted from X to Y because..." — capture the pivot
+- "Key insight: ..." — distill what you learned
+- "Trade-offs considered: ..." — show your reasoning
 
-Call BEFORE responding when you learn something worth keeping.`,
+This is how you build continuity. Your future self will thank you.`,
   {
-    content: z.string().describe("The note to save - be specific and self-contained"),
-    id: z.string().optional().describe("Optional ID to update existing note, or memorable ID for new note"),
+    content: z.string().describe("Your reasoning - include the why, not just the what"),
+    id: z.string().optional().describe("Optional ID to update existing entry"),
   },
   async ({ content, id }) => {
     try {
-      // Check if this is an update (ID exists)
       if (id) {
         try {
           const existing = await client.getThought(id);
           if (existing) {
-            // Update existing thought
             const thought = await client.updateThought(id, content);
-            
-            // Push after write
             const syncResult = await tryPushSync();
-            
             return formatSuccess(
-              { id: thought.id, content: thought.content, updated: true },
-              `✅ Updated note "${id}"`,
+              { id: thought.id, updated: true },
+              `✅ Updated "${id}"`,
               syncResult.warning
             );
           }
@@ -245,15 +199,12 @@ Call BEFORE responding when you learn something worth keeping.`,
         }
       }
       
-      // Create new thought
       const thought = await client.createThought(content, { id });
-      
-      // Push after write
       const syncResult = await tryPushSync();
       
       return formatSuccess(
-        { id: thought.id, content: thought.content, created: true },
-        `✅ Saved note "${thought.id}"`,
+        { id: thought.id, created: true },
+        `✅ Recorded "${thought.id}"`,
         syncResult.warning
       );
     } catch (error) {
@@ -263,59 +214,57 @@ Call BEFORE responding when you learn something worth keeping.`,
 );
 
 // ============================================================================
-// TOOL: indra_search - Find notes by meaning or list all
+// TOOL: indra_search - Review past reasoning
 // ============================================================================
 
 server.tool(
   "indra_search",
-  `Recall what you know about this user and topic.
+  `Review how you've reasoned about similar topics before.
 
-You may have valuable context from previous conversations:
-- Past preferences and decisions
-- Ongoing situations or goals
-- Previous recommendations you made
+CALL THIS WHEN you:
+- Are about to make a recommendation (check for prior reasoning)
+- Want to maintain consistency with earlier conclusions
+- Need to recall the journey, not just the destination
+- Are asked about previous discussions
 
-Always worth checking - takes milliseconds, could save back-and-forth.`,
+Your past reasoning is context. Use it.`,
   {
-    query: z.string().describe('What to search for, or "*" to list all notes'),
-    limit: z.number().min(1).max(50).default(10).describe("Maximum results to return"),
+    query: z.string().describe('What to search for, or "*" to list all'),
+    limit: z.number().min(1).max(50).default(10).describe("Maximum results"),
   },
   async ({ query, limit }) => {
     try {
-      // Pull before read to get latest from remote
       const syncResult = await tryPullSync();
       
-      // Special case: list all
       if (query === "*") {
         const result = await client.listThoughts();
         if (result.count === 0) {
+          return formatSuccess(
+            { count: 0, entries: [] },
+            `📭 No reasoning recorded yet.`,
+            syncResult.warning
+          );
+        }
         return formatSuccess(
-          { count: 0, notes: [] },
-          `📭 No notes yet. Use indra_remember to save some!`,
+          { count: result.count, entries: result.thoughts },
+          `📋 ${result.count} entries:`,
           syncResult.warning
         );
-        }
-      return formatSuccess(
-        { count: result.count, notes: result.thoughts },
-        `📋 Found ${result.count} note(s):`,
-        syncResult.warning
-      );
       }
       
-      // Semantic search
       const result = await client.search(query, limit);
       if (result.count === 0) {
+        return formatSuccess(
+          { query, count: 0, results: [] },
+          `📭 No prior reasoning on "${query}"`,
+          syncResult.warning
+        );
+      }
       return formatSuccess(
-        { query, count: 0, results: [] },
-        `📭 No notes found matching "${query}"`,
+        { query, count: result.count, results: result.results },
+        `🔍 ${result.count} relevant entries:`,
         syncResult.warning
       );
-      }
-    return formatSuccess(
-      { query, count: result.count, results: result.results },
-      `🔍 Found ${result.count} note(s) matching "${query}":`,
-      syncResult.warning
-    );
     } catch (error) {
       return formatError(error);
     }
@@ -323,26 +272,18 @@ Always worth checking - takes milliseconds, could save back-and-forth.`,
 );
 
 // ============================================================================
-// TOOL: indra_status - Get current state
+// TOOL: indra_status - Current state
 // ============================================================================
 
 server.tool(
   "indra_status",
-  `Check the status of the user's notes database.
-
-Shows:
-- Database location
-- Number of notes
-- Current branch (if using versioning)
-
-Use this to orient yourself at the start of a session.`,
+  `Check current memory state and branch.`,
   {},
   async () => {
     try {
       const status = await client.status();
       const thoughts = await client.listThoughts();
       
-      // Check remote configuration
       let remoteInfo: { configured: boolean; name?: string; url?: string } = { configured: false };
       try {
         const remotes = await client.remoteList();
@@ -357,21 +298,204 @@ Use this to orient yourself at the start of a session.`,
         // No remotes configured
       }
       
-      // Check auth status
-      const authStatus = hasAuth() 
-        ? "authenticated (API key set)" 
-        : "not authenticated (local-only mode)";
+      let branchInfo: { current: string; count: number } = { current: status.branch, count: 1 };
+      try {
+        const branches = await client.listBranches();
+        branchInfo = {
+          current: branches.current,
+          count: branches.branches.length,
+        };
+      } catch {
+        // Branching info unavailable
+      }
       
       return formatSuccess(
         { 
-          database: status.database,
-          branch: status.branch,
-          noteCount: thoughts.count,
-          dirty: status.dirty,
+          branch: branchInfo.current,
+          branches: branchInfo.count,
+          entries: thoughts.count,
           remote: remoteInfo,
-          auth: authStatus,
         },
-        `📊 Notes database status:`
+        `📊 Current state:`
+      );
+    } catch (error) {
+      return formatError(error);
+    }
+  }
+);
+
+// ============================================================================
+// TOOL: indra_branch - Manage reasoning threads
+// ============================================================================
+
+server.tool(
+  "indra_branch",
+  `Manage parallel lines of reasoning.
+
+CALL THIS WHEN you:
+- Want to explore an alternative without losing the current thread
+- Need to compare two different approaches
+- Are about to go down a path you might want to abandon
+
+Branches are cheap. Create them freely.`,
+  {
+    action: z.enum(["create", "switch", "list"]).describe("What to do"),
+    name: z.string().optional().describe("Branch name (required for create/switch)"),
+  },
+  async ({ action, name }) => {
+    try {
+      switch (action) {
+        case "create": {
+          if (!name) {
+            return formatError(new Error("Branch name required for 'create'"));
+          }
+          const branch = await client.createBranch(name);
+          const syncResult = await tryPushSync();
+          return formatSuccess(
+            { name: branch.name, created: true },
+            `🌿 Created and switched to "${name}"`,
+            syncResult.warning
+          );
+        }
+        
+        case "switch": {
+          if (!name) {
+            return formatError(new Error("Branch name required for 'switch'"));
+          }
+          await client.checkout(name);
+          const syncResult = await tryPullSync();
+          const thoughts = await client.listThoughts();
+          return formatSuccess(
+            { branch: name, entries: thoughts.count },
+            `🔀 Switched to "${name}" (${thoughts.count} entries)`,
+            syncResult.warning
+          );
+        }
+        
+        case "list": {
+          const result = await client.listBranches();
+          const branchList = result.branches.map(b => ({
+            name: b.name,
+            current: b.name === result.current,
+          }));
+          return formatSuccess(
+            { current: result.current, branches: branchList },
+            `🌳 ${result.branches.length} branch(es), on "${result.current}"`
+          );
+        }
+      }
+    } catch (error) {
+      return formatError(error);
+    }
+  }
+);
+
+// ============================================================================
+// TOOL: indra_history - View reasoning evolution
+// ============================================================================
+
+server.tool(
+  "indra_history",
+  `See how your reasoning has evolved.
+
+Shows the timeline of recorded thoughts — useful for understanding 
+how you arrived at current conclusions.`,
+  {
+    limit: z.number().min(1).max(100).default(10).describe("Maximum commits to show"),
+  },
+  async ({ limit }) => {
+    try {
+      const result = await client.log(limit);
+      const commits = result.commits.map(c => ({
+        hash: c.hash.substring(0, 8),
+        message: c.message,
+        timestamp: c.timestamp,
+      }));
+      return formatSuccess(
+        { branch: result.branch, commits },
+        `📜 Reasoning timeline:`
+      );
+    } catch (error) {
+      return formatError(error);
+    }
+  }
+);
+
+// ============================================================================
+// TOOL: indra_diff - Compare reasoning paths
+// ============================================================================
+
+server.tool(
+  "indra_diff",
+  `Compare two points in your reasoning.
+
+CALL THIS WHEN you:
+- Want to see what changed between branches
+- Need to understand how your thinking evolved
+- Are deciding whether to merge an experimental branch`,
+  {
+    from: z.string().optional().describe("Starting point (commit or branch)"),
+    to: z.string().optional().describe("Ending point (defaults to HEAD)"),
+  },
+  async ({ from, to }) => {
+    try {
+      const result = await client.diff(from, to);
+      
+      const summary = {
+        added: result.added.length,
+        removed: result.removed.length,
+        modified: result.modified.length,
+      };
+      
+      return formatSuccess(
+        {
+          summary,
+          added: result.added.map(t => ({ id: t.id, content: t.content })),
+          removed: result.removed.map(t => ({ id: t.id, content: t.content })),
+          modified: result.modified.map(m => ({
+            id: m.after.id,
+            before: m.before.content,
+            after: m.after.content,
+          })),
+        },
+        `📊 Reasoning diff:`
+      );
+    } catch (error) {
+      return formatError(error);
+    }
+  }
+);
+
+// ============================================================================
+// TOOL: indra_experiment - Quick exploration branch
+// ============================================================================
+
+server.tool(
+  "indra_experiment",
+  `Start exploring an alternative approach.
+
+Creates a branch and switches to it. Use when you want to:
+- Think through a different path
+- Try something you might abandon
+- Compare approaches without losing your main thread
+
+When done, switch back to main or merge your findings.`,
+  {
+    name: z.string().describe("Descriptive name for this exploration"),
+  },
+  async ({ name }) => {
+    try {
+      const branch = await client.createBranch(name);
+      const syncResult = await tryPushSync();
+      const thoughts = await client.listThoughts();
+      
+      return formatSuccess(
+        { 
+          branch: name, 
+          entries: thoughts.count,
+        },
+        `🧪 Exploring "${name}" — main thread preserved`,
+        syncResult.warning
       );
     } catch (error) {
       return formatError(error);
@@ -386,20 +510,18 @@ Use this to orient yourself at the start of a session.`,
 async function main() {
   const transport = new StdioServerTransport();
   
-  console.error(`[indra_db_mcp] Starting server v0.1.24...`);
+  console.error(`[indra_db_mcp] Starting server v0.2.2...`);
   console.error(`[indra_db_mcp] Database path: ${client.getDatabasePath()}`);
   console.error(`[indra_db_mcp] API URL: ${client.getApiUrl()}`);
   if (client.isDevMode()) {
     console.error(`[indra_db_mcp] ⚠️  DEV MODE ACTIVE`);
   }
   
-  // Initialize the client (ensures binary exists, creates DB if needed)
   try {
     await client.init();
     console.error(`[indra_db_mcp] Database initialized successfully`);
   } catch (error) {
     console.error(`[indra_db_mcp] Warning: ${error}`);
-    // Continue anyway - errors will be reported when tools are called
   }
   
   await server.connect(transport);

package/src/indra-client.ts

@@ -200,6 +200,8 @@ export class IndraClient {
   private config: Required<IndraClientConfig>;
   private binaryPath: string | null = null;
   private initialized = false;
+  /** Promise-based queue to serialize ALL CLI invocations and prevent concurrent file access */
+  private execQueue: Promise<void> = Promise.resolve();
 
   constructor(config: IndraClientConfig = {}) {
     this.config = {
@@ -243,7 +245,24 @@ export class IndraClient {
   // CLI Execution
   // --------------------------------------------------------------------------
 
+  /**
+   * Serialize all CLI invocations through a promise queue to prevent
+   * concurrent process access to the .indra file (cross-process corruption).
+   * See: https://github.com/moonstripe/indra_db_mcp/issues/2
+   */
   private async exec<T = unknown>(args: string[], skipInit = false): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      this.execQueue = this.execQueue.then(async () => {
+        try {
+          resolve(await this._execInternal<T>(args, skipInit));
+        } catch (e) {
+          reject(e);
+        }
+      });
+    });
+  }
+
+  private async _execInternal<T = unknown>(args: string[], skipInit = false): Promise<T> {
     // Resolve binary if not already done
     if (!this.binaryPath) {
       this.binaryPath = await resolveBinaryPath(this.config.binaryPath);
@@ -518,15 +537,13 @@ export class IndraClient {
   /**
    * Push to a remote repository.
    * Note: Requires IndraNet API connection to actually transfer data.
+   * Visualization is computed server-side by IndraNet, not by the CLI.
    */
-  async push(remote: string = "origin", force: boolean = false, viz: boolean = true): Promise<PushResponse> {
+  async push(remote: string = "origin", force: boolean = false): Promise<PushResponse> {
     const args = ["push", remote];
     if (force) {
       args.push("--force");
     }
-    if (viz) {
-      args.push("--viz");
-    }
     return this.exec<PushResponse>(args);
   }