Wormhole | Local Shared Memory for AI Agents

Why Wormhole?

Built for Developer Workflows

100% Private

All data stored locally in SQLite. Nothing leaves your machine.

Universal Logging

Single log tool for any action type.

Session Management

Named work sessions with context isolation.

Token Optimized

~400 tokens vs ~5,000 without optimization.

Conflict Detection

Know when agents touch the same files.

Stale Event Rejection

Auto-validates edits. Outdated changes filtered.

Quick Start

Installation

1

Configure Your Agent

Claude Code: Add to ~/.claude.json

{
  "mcpServers": {
    "wormhole": {
      "command": "npx",
      "args": ["-y", "wormhole-mcp"]
    }
  }
}

GitHub Copilot: Add to .vscode/mcp.json in your project:

{
  "servers": {
    "wormhole": {
      "command": "npx",
      "args": ["-y", "wormhole-mcp"]
    }
  }
}

2

Ready

Restart your agent and start sharing context across tools. All data stays on your machine.

Alternative: Global Install

npm install -g wormhole-mcp

Then use "command": "wormhole-mcp" in your config.

API Reference

MCP Tools

log

Universal logging for any action type.

log({
  action: "cmd_run",
  agent_id: "claude-code",
  project_path: "/path/to/project",
  content: { command: "npm test", exit_code: 0 }
})

cmd_runfile_editdecisiontest_resultfeedbacktodosplan_output

get_recent

Get recent activity with compact output.

get_recent({ project_path: "/path/to/project" })

[5m] claude: npm test → ✓ [8m] cursor: edit auth.ts "Add JWT"

check_conflicts

Detect concurrent file edits.

check_conflicts({ project_path: "/path/to/project" })

cleanup

Clean up events with scopes.

cleanup({ scope: "project", project_path: "/path/to/project" })

save_knowledge

Store decisions, pitfalls, conventions, or constraints.

save_knowledge({
  project_path: ".",
  knowledge_type: "pitfall",
  title: "Avoid fs.readFileSync",
  content: "Blocks event loop; causes timeouts"
})

search_project_knowledge

Intent-aware lookup of saved knowledge.

search_project_knowledge({
  project_path: ".",
  intent: "debugging",
  query: "auth"
})

Workflow

Session Management

start_session

start_session({
  project_path: "/path/to/project",
  agent_id: "claude-code",
  name: "bugfix-auth"
})

list_sessions

list_sessions({ project_path: "/path/to/project" })

● bugfix-auth (2h) by claude ○ feature-payment (1d) by cursor

end_session

end_session({
  session_id: "abc-123",
  summary: "Fixed timeout issue"
})

Sessions isolate context. Use switch_session to resume previous work.

Visualization

Dashboard UI

Monitor agent activity, browse sessions, and analyze workflow patterns.

Reads from: ~/.wormhole/timeline.db

Wormhole Dashboard

247Events

12Sessions

3Active

4Agents

File edit: auth.ts

Command: npm test

Decision: Use JWT

npx wormhole ui

Opens at http://localhost:3000

Real-time activity feed

Search & filter events

Export to JSON

Knowledge Capture

Save decisions & pitfalls and surface them with intent-aware search.

Keyboard shortcuts

Integrations

Agent Setup

Configure your AI agents to use Wormhole's shared memory.

Claude Code

Full plugin with MCP config and skill bundled.

claude /install-plugin \
    ./node_modules/wormhole-mcp/plugins/wormhole

Or use standalone skill:

cp -r node_modules/wormhole-mcp/skills/wormhole \
    .claude/skills/

GitHub Copilot

Add MCP support in VS Code. Copy to .vscode/mcp.json:

{
    "servers": {
        "wormhole": {
            "command": "npx",
            "args": ["-y", "wormhole-mcp"]
        }
    }
}

Cursor

Same MCP config works for Cursor. Add to your MCP settings.

{
    "mcpServers": {
        "wormhole": {
            "command": "npx",
            "args": ["-y", "wormhole-mcp"]
        }
    }
}

Local Storage

Configuration

All data stored locally on your machine. No accounts, no cloud sync, no telemetry.

Config: ~/.wormhole/config.json

{
  "retention_hours": 24,
  "max_payload_chars": 200,
  "auto_cleanup": true,
  "default_detail": "minimal",
  "default_limit": 5
}

Database: ~/.wormhole/timeline.db

Archives: ~/.wormhole/archives/