🐉 Wyrm — the memory layer for AI assistants

Your AI doesn't just need memory. It needs the layer that turns memory into compounding leverage.

What Wyrm actually is

Wyrm is not "AI memory." It's the substrate that turns one-shot AI conversations into accreting intelligence. Five things, only one of which is memory:

1. ⌇ Memory across sessions, tools, and projects. Your AI inherits prior state instead of starting cold every conversation. Works with Claude / Copilot / Cursor / Windsurf / Codex.
2. ✖ Counter-pattern blocking. When an approach fails, Wyrm records it. Next time, your AI is blocked from suggesting the same failed thing again. Other memory tools learn only from success — Wyrm learns from failure too.
3. → Autonomous goal pursuit (OODA agent loop). Set a persistent goal ("ship v2", "keep deps current weekly"), and the wyrm-loop daemon runs Observe→Orient→Decide→Act iterations until success criteria are met.
4. ↯ Federation. Wyrm calls other MCP servers (GitHub, Slack, Linear, …) as tools. Buddy Protocol v1.0 lets Wyrm talk to other AI memory tools. Composes your whole stack into one mind.
5. ✺ Creative substrate. First-class design tokens (colour / type / spacing / motion / shadow / radius / breakpoint) and a tagged design-reference clipper — Wyrm is not just for code.

You: "What did we decide about the auth architecture last week?"
AI:  *calls wyrm_session_prime* "We went with JWT + refresh tokens, stored
      in httpOnly cookies. Truth #142 cites the Tuesday session — there's
      a downstream impact on the OAuth flow we should check first."

You don't ask for memory. The AI cites it on its own. Visibly, with sources.

New in 6.0 — "Present"

• 🐉 Live statusline — wyrm-statusline binary renders Wyrm's live state into your Claude Code (or Cursor / Windsurf) statusline: 🐉 Wyrm · ProjectName · 3 ⟶ · ~12k saved · ⬢ 7. Auto-spawned daemon, idle-times-out, privacy mode for screen-shares.
• ✧ Cross-project memory — wyrm_constellation queries FTS5 across every registered Wyrm project at once. "Have I solved this before in any project?" Privacy-gated: per-row cross_project_visibility defaults to 'within'.
• ▰ Tool profiles — essential / standard / full profiles auto-detected per client. VS Code Copilot / Cursor / Antigravity see a curated 27-tool surface; Claude Code / Codex / unknown clients get all 126. No functionality removed.
• ⊡ Cache markers — wyrm_context_build segregates a stable preamble for Anthropic prompt-caching (10× cost cut on cached portions).
• ↺ wyrm_migrate_prompt — rewrite Wyrm-managed blocks in .cursor/rules, .github/copilot-instructions.md, CLAUDE.md idempotently. Operator content outside the markers is preserved verbatim.

Enable the statusline in Claude Code:

{ "statusLine": { "type": "command", "command": "wyrm-statusline", "padding": 0 } }

What's in the box (126 MCP tools)

• ⌇ Memory — projects, sessions, quests, ground truths, memory artifacts, hybrid FTS5 + vector search
• ✖ Counter-pattern — failure check / record / resolve, blocks repeated mistakes at suggestion time
• ⬢ Ground truths — validated facts versioned with cascade-invalidation when upstream changes
• ✱ Decision chain — wyrm_decided_because, decision_upstream / _downstream, blast-radius traversal
• → Agent loop — wyrm_goal_set, wyrm_agent_init, daemon runs OODA until success criteria are met
• ↯ Federation — wyrm_mcp_register for outbound MCP, Buddy Protocol v1.0 for peer AI tools
• 🕸 Knowledge graph — entity / relationship graph with shortest-path and neighborhood queries
• 🎨 Design substrate — design_tokens + tagged design_references library
• 🛡 Audit chain — hash-chained, Ed25519-signable audit log for SOC2 / HIPAA
• 💰 Hour ledger + invoicing — generate invoices from session content
• 🌐 Federated team sync — per-row is_shared flag; PII never leaves your box unless explicitly shared
• 🔒 Encryption — AES-256-GCM; keys never leave your machine
• 👁 Visibility tools — wyrm_intro + wyrm_digest make Wyrm's work product legible to humans

Built for these workflows

• Founders with multi-product portfolios — cross-project memory makes patterns from project A inform project B
• Designers / creatives — design tokens + reference clipper turn Wyrm into a creative substrate, not just a code-memory tool
• Co-founders / operators — wyrm_digest shows what Wyrm did this week in plain English
• Long-running autonomous work — agent loop runs your standing goals overnight
• 🧠 Memory Artifacts — Store lessons, patterns, anti-patterns, heuristics with confidence scoring and lifecycle tracking
• 🧱 Ground Truths — Versioned, validated project facts injected into every AI context build
• 🧭 Reasoning Scaffolds — Structured checklists surfaced automatically when task type matches
• 🔬 Distillation Queue — Batch-extract session knowledge into reviewed, curated memory
• 🔍 Hybrid Search — Reciprocal Rank Fusion combining FTS5 + vector candidates

Installation

npm (recommended)

npm install -g wyrm-mcp

Homebrew (macOS / Linux)

brew tap ghosts-lk/wyrm
brew install wyrm-mcp

Docker

docker run -d -p 3000:3000 -v wyrm-data:/data ghcr.io/ghosts-lk/wyrm-mcp:latest

Or with Docker Compose:

curl -O https://raw.githubusercontent.com/Ghosts-Protocol-Pvt-Ltd/Wyrm/main/docker-compose.yml
docker compose up -d

npx (no install)

npx wyrm-mcp

Quick Start

1. Install

npm install -g wyrm-mcp

2. Connect to Your AI

Add Wyrm to your AI client's MCP configuration:

Edit ~/.config/claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "wyrm": {
      "command": "wyrm-mcp"
    }
  }
}

Add to .vscode/settings.json or your user settings:

{
  "mcp": {
    "servers": {
      "wyrm": {
        "command": "wyrm-mcp"
      }
    }
  }
}

Add to ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "wyrm": {
      "command": "wyrm-mcp"
    }
  }
}

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "wyrm": {
      "command": "wyrm-mcp"
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "wyrm": {
      "command": "wyrm-mcp"
    }
  }
}

Or run wyrm-setup to auto-detect and configure all installed AI clients at once.

3. Enable Semantic Search (Optional but Recommended)

Wyrm uses hybrid search (FTS5 + semantic vectors) when Ollama is running locally. No configuration needed — Wyrm auto-detects it.

# Install Ollama: https://ollama.com
ollama pull nomic-embed-text

That's it. Once nomic-embed-text is available, wyrm_search automatically upgrades from keyword-only to hybrid semantic+keyword search using Reciprocal Rank Fusion. If Ollama isn't running, Wyrm falls back to FTS5 silently — no errors, no config changes required.

To use OpenAI embeddings instead:

WYRM_VECTOR_PROVIDER=openai OPENAI_API_KEY=sk-... wyrm-mcp

4. Use It

Once connected, your AI has access to all Wyrm tools. Try:

"Scan ~/projects for git repositories"
"Start a session for my auth refactor"
"What quests are pending across all projects?"
"Search my memory for anything about database migrations"

MCP Tools Reference

Wyrm exposes 38 tools via the Model Context Protocol:

Projects

| Tool | Description | |------|-------------| | wyrm_scan_projects | Discover git projects in a directory tree | | wyrm_list_projects | List all registered projects with metadata | | wyrm_project_context | Get full context for a project (sessions, quests, data) | | wyrm_global_context | Overview across all projects |

Sessions

| Tool | Description | |------|-------------| | wyrm_session_start | Start or continue a named session with context | | wyrm_session_update | Update session with completed work, decisions, and notes |

Quests (Task Tracking)

| Tool | Description | |------|-------------| | wyrm_quest_add | Add a task with priority, tags, and description | | wyrm_quest_complete | Mark a task as done with completion notes | | wyrm_all_quests | List pending tasks across all projects |

Data Lake

| Tool | Description | |------|-------------| | wyrm_data_insert | Store a data point with namespace and metadata | | wyrm_data_batch_insert | Bulk insert for large datasets | | wyrm_data_query | Query stored data by namespace, key, or content | | wyrm_data_categories | List all data categories for a project |

Skills Registry

| Tool | Description | |------|-------------| | wyrm_skill_register | Register or update a skill with metadata | | wyrm_skill_list | List skills with filtering options | | wyrm_skill_get | Get detailed skill information | | wyrm_skill_search | Search skills by name, description, or tags | | wyrm_skill_activate / wyrm_skill_deactivate | Toggle skill status | | wyrm_skill_delete | Remove a skill | | wyrm_skill_stats | Skill registry statistics |

Search & Utilities

| Tool | Description | |------|-------------| | wyrm_search | Full-text search across all projects, sessions, quests, and data | | wyrm_set_global | Set global context that applies across all projects | | wyrm_sync | Sync database with .wyrm/ markdown files | | wyrm_stats | Database statistics and health | | wyrm_usage | Token usage stats, cache hit rates, and cost estimates | | wyrm_maintenance | Vacuum, archive old data, optimize indexes | | wyrm_setup | Auto-configure Wyrm in all detected AI clients |

Auto-Orchestration

| Tool | Description | |------|-------------| | wyrm_orchestrate_task | Classify a task and get an orchestration plan | | wyrm_orchestration_config | View or update orchestration settings | | wyrm_orchestration_stats | Orchestration effectiveness and task distribution |

Knowledge Graph

| Tool | Description | |------|-------------| | wyrm_entity_add | Add a named entity to the project's knowledge graph | | wyrm_entity_link | Create a typed, directional relationship between two entities | | wyrm_entity_search | Find entities by name or alias | | wyrm_entity_graph | Get the neighborhood graph around an entity (recursive traversal) | | wyrm_entity_path | Find shortest path between two entities | | wyrm_entity_merge | Merge two duplicate entities, consolidating aliases and relationships |

Memory Artifacts

| Tool | Description | |------|-------------| | wyrm_remember | Store a distilled memory artifact — pattern, lesson, anti-pattern, heuristic, or reasoning trace | | wyrm_recall | Retrieve relevant memory artifacts for a task using 2-stage FTS + tag retrieval with confidence scoring | | wyrm_feedback | Record whether a recalled artifact was helpful (updates confidence via Bayesian adjustment) | | wyrm_context_build | Assemble a task-specific context brief: ground truths + best scaffold + relevant memory artifacts |

Intelligence Amplification

| Tool | Description | |------|-------------| | wyrm_truth_set | Store a validated ground truth (architecture, constraints, decisions) — versioned, history preserved | | wyrm_truth_get | Retrieve all current ground truths for a project, optionally filtered by category | | wyrm_scaffold_save | Save a reasoning scaffold — structured step-by-step checklist for a problem type | | wyrm_scaffold_get | Find the best matching reasoning scaffold for a task description | | wyrm_distill | Queue candidate memory artifacts from a session for human review | | wyrm_review | Approve (activate) or reject (delete) a queued distillation artifact |

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | WYRM_DB_PATH | ~/.wyrm/wyrm.db | SQLite database location | | WYRM_ENCRYPTION_KEY | (none) | AES-256-GCM encryption key for sensitive data | | WYRM_LOG_LEVEL | info | Logging level (debug, info, warn, error) | | WYRM_HTTP_PORT | 3333 | HTTP API server port |

Encryption

To enable encryption for sensitive context data:

# Generate a key
openssl rand -hex 32

# Set it before starting Wyrm
export WYRM_ENCRYPTION_KEY="your-64-char-hex-key"

All encryption happens locally. Keys never leave your machine.

Per-Project Files

Each tracked project gets a .wyrm/ directory:

project/
└── .wyrm/
    ├── hoard.md        # 🐉 Project knowledge — architecture, decisions, context
    ├── chronicles.md   # 📜 Session history — what was discussed and built
    ├── quests.md       # ⚔️ Task queue — pending and completed work
    └── protocol.md     # 🔥 AI guidelines — project-specific instructions

These sync bi-directionally with the SQLite database via wyrm_sync.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    AI Assistants                         │
│     (Copilot · Claude · Cursor · Windsurf · Zed)        │
└────────────────────────┬────────────────────────────────┘
                         │ MCP (stdio)
                         ▼
┌─────────────────────────────────────────────────────────┐
│                  Wyrm MCP Server                        │
│                                                         │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Intelligence Layer                               │   │
│  │  Ground Truths · Reasoning Scaffolds · Distill    │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Memory Artifacts · Knowledge Graph               │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐  │
│  │ Projects │  │ Sessions │  │  Quests  │  │ Skills │  │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐  │
│  │ DataLake │  │  Hybrid  │  │  Crypto  │  │  Sync  │  │
│  │          │  │  Search  │  │(AES-256) │  │  (.md) │  │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘  │
│                                                         │
│              SQLite Database (WAL mode)                  │
│              Optional HTTP API (:3333)                   │
└─────────────────────────────────────────────────────────┘

Stack: TypeScript · Node.js · better-sqlite3 · FTS5 · MCP SDK

Development

# Clone and install
git clone https://github.com/Ghosts-Protocol-Pvt-Ltd/Wyrm.git
cd Wyrm/packages/mcp-server
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run dev

Project Structure

Wyrm/
├── packages/
│   ├── mcp-server/          # Core MCP server
│   │   ├── src/
│   │   │   ├── index.ts     # MCP tool definitions & server
│   │   │   ├── database.ts  # SQLite schema & queries
│   │   │   ├── crypto.ts    # AES-256-GCM encryption
│   │   │   ├── security.ts  # Input sanitization
│   │   │   └── ...
│   │   ├── tests/           # Jest test suite
│   │   └── package.json
│   └── vscode-extension/    # VS Code extension (optional)
├── config/                  # Configuration templates
├── templates/               # Project template files
├── docs/                    # Documentation
├── examples/                # Usage examples
└── scripts/                 # Utility scripts

Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

Please ensure tests pass (npm test) and the project builds (npm run build) before submitting.

Security

• Local-only — All data stored on your machine. Nothing leaves by default.
• No telemetry — Zero data collection, zero phone-home.
• Optional encryption — AES-256-GCM for sensitive context data.
• Audited — Security audits documented in SECURITY_AUDIT.md and SECURITY_AUDIT_V2.md.

Found a vulnerability? Please open an issue or email [email protected].

License

AGPL-3.0 — Copyright © 2024-2026 Ghost Protocol (Pvt) Ltd

For commercial licensing (e.g. embedding Wyrm in proprietary products), contact [email protected].

The dragon remembers. 🐉

Built by Ghost Protocol