waggle-os/packages/memory-mcp

waggle-memory-mcp

Persistent memory MCP server for Claude Code, Claude Desktop, and any MCP-compatible AI system.

Give your AI assistant memory that persists across conversations — facts, decisions, preferences, project context, and a knowledge graph of entities and relationships.

Powered by the Waggle OS memory engine.

Features

• Persistent Memory — Save and recall facts, decisions, preferences across conversations
• Semantic Search — Hybrid FTS5 keyword + sqlite-vec vector search with RRF fusion
• Knowledge Graph — Entities (people, projects, concepts) and their relationships
• Identity — Persistent user profile (name, role, capabilities)
• Awareness — Short-lived context markers for active tasks and flags
• Workspaces — Isolated memory spaces for different projects
• Harvest — Import conversation history from ChatGPT, Claude, Gemini, and more
• Zero Config Embeddings — Offline vector search using a local ONNX model (23MB, auto-downloaded)
• Shared Data — Same ~/.waggle/ directory as Waggle OS desktop app

Installation

Claude Code

Add to ~/.claude/settings.json:

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

Claude Desktop

Add to ~/.claude/claude_desktop_config.json:

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

Custom Data Directory

{
  "mcpServers": {
    "waggle-memory": {
      "command": "npx",
      "args": ["-y", "waggle-memory-mcp"],
      "env": {
        "WAGGLE_DATA_DIR": "/path/to/your/.waggle"
      }
    }
  }
}

Tools

Tool	Description
save_memory	Save a memory (fact, decision, preference) with importance level
recall_memory	Semantic search across memories with scoring profiles
search_entities	Search the knowledge graph for entities
save_entity	Create or update an entity in the knowledge graph
create_relation	Create a relationship between entities
get_identity	Get the user's persistent identity profile
set_identity	Create or update identity (name, role, etc.)
get_awareness	Get active tasks, pending items, context flags
set_awareness	Set a short-lived awareness item
clear_awareness	Remove awareness items by ID or category
list_workspaces	List all workspaces with memory stats
create_workspace	Create a new isolated workspace
harvest_import	Import conversations from ChatGPT, Claude, Gemini
harvest_sources	List registered harvest sources and sync status

Resources

URI	Description
memory://personal/stats	Frame count, entity count, embedding provider status
memory://identity	Current identity profile
memory://awareness	Active awareness items
memory://workspace/{id}	Workspace config and memory stats

Architecture

~/.waggle/
├── personal.mind          ← SQLite database (WAL mode + sqlite-vec)
├── models/                ← Cached ONNX embedding model
├── config.json            ← Settings
└── workspaces/
    └── {id}/
        ├── workspace.json ← Workspace config
        └── workspace.mind ← Workspace SQLite database

Memory Model

• I-Frame (Identity): Base facts — "User prefers TypeScript"
• P-Frame (Procedural): Updates to I-Frames
• B-Frame (Bridging): Links between frames

Search Pipeline

1. FTS5 keyword search (stop-word filtered, OR-based)
2. sqlite-vec k-NN vector search (1024-dim embeddings)
3. RRF fusion (K=60) combines both result sets
4. Relevance scoring with 4 profiles: balanced, recent, important, connected

Embedding Provider Chain

Probed in order, first success wins:

1. InProcess — all-MiniLM-L6-v2 ONNX model, zero config, ~23MB download
2. Ollama — nomic-embed-text (requires local Ollama)
3. Voyage/OpenAI — API-based (requires API keys)
4. Mock — Deterministic fallback (always works, no semantic quality)

Environment Variables

Variable	Description	Default
WAGGLE_DATA_DIR	Data directory path	~/.waggle
WAGGLE_EMBEDDING_PROVIDER	Force a specific provider	auto
WAGGLE_OLLAMA_URL	Ollama server URL	http://localhost:11434
WAGGLE_OLLAMA_MODEL	Ollama model name	nomic-embed-text
WAGGLE_VOYAGE_API_KEY	Voyage AI API key	—
WAGGLE_OPENAI_API_KEY	OpenAI API key	—

Shared with Waggle OS

If you also run Waggle OS desktop, this MCP server shares the same data directory. Memories saved in Claude Code appear in Waggle OS and vice versa. SQLite WAL mode supports concurrent readers.

Development

# From the waggle-os monorepo root
cd packages/memory-mcp
npm install
npm run build
npm start

License

MIT - Egzakta Group