ricord-mcp

Persistent memory for AI coding assistants. Ricord gives your AI tools long-term knowledge, episodic memory, a knowledge graph, integrations, and more — all via the Model Context Protocol.

This package ships two binaries:

• ricord-mcp — the MCP server, for Claude Code / Cursor / Windsurf / VS Code
• ricord — a CLI for repo ingestion (ricord init), auth (ricord login), and account info (ricord whoami)

Both share ~/.ricord/credentials.json, so logging in once authorizes everything.

Quick Start (One Command)

npx ricord-mcp --setup --client claude --api-key YOUR_API_KEY

Supported clients: claude-code, claude-desktop, cursor, windsurf, vscode

This auto-writes the correct config file for your editor. Get your API key at ricord.ai/dashboard/api-keys.

Manual Setup

claude mcp add ricord -- npx ricord-mcp --api-key YOUR_API_KEY

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ricord": {
      "command": "npx",
      "args": ["ricord-mcp", "--api-key", "YOUR_API_KEY"]
    }
  }
}

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "ricord": {
      "command": "npx",
      "args": ["ricord-mcp", "--api-key", "YOUR_API_KEY"]
    }
  }
}

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

{
  "mcpServers": {
    "ricord": {
      "command": "npx",
      "args": ["ricord-mcp", "--api-key", "YOUR_API_KEY"]
    }
  }
}

Add to .vscode/mcp.json:

{
  "servers": {
    "ricord": {
      "command": "npx",
      "args": ["ricord-mcp", "--api-key", "YOUR_API_KEY"]
    }
  }
}

Options

| Flag | Env Var | Default | Description | |------|---------|---------|-------------| | --api-key | RICORD_API_KEY | required | Your Ricord API key | | --api-base | RICORD_API_BASE | https://api.ricord.ai | API endpoint | | --mode | — | auto | auto, manual, or hybrid | | --project | RICORD_PROJECT | — | Project namespace |

Modes

• auto (default) — AI automatically saves knowledge when you make decisions, state preferences, or discuss architecture
• manual — Only saves when explicitly asked
• hybrid — Auto-extracts knowledge but marks it as draft for your review

Tools (9)

| Tool | Description | Credits | |------|-------------|---------| | ricord_remember | Save facts, preferences, decisions, procedures, references, playbooks, anti-patterns, episodes | 3 | | ricord_recall | Retrieve relevant knowledge (hybrid vector + graph search) | 1 | | ricord_correct | Update existing knowledge by ID | 3 | | ricord_forget | Delete knowledge items by ID | 0 | | ricord_list | Browse stored items with optional type filter | 0 | | ricord_profile | Get or update aggregated user profile | 0 | | ricord_graph | Explore knowledge graph: entities, neighborhoods, stats, communities | 0 | | ricord_usage | Check credit balance, tier, and usage stats | 0 |

Prompts

Setup prompts are included for each supported client:

• setup-claude-code
• setup-claude-desktop
• setup-cursor
• setup-windsurf
• setup-vscode

Repo ingestion (ricord init)

Once installed, the ricord CLI walks any repository, builds a structured per-directory bundle (imports, exports, top-of-file docs, cross-directory "Used by" inversion), and ingests it into your knowledge graph.

# One-time setup — opens the browser for OAuth and stores ~/.ricord/credentials.json
ricord login

# Ingest the current repo
ricord init

# Or any directory
ricord init --root /path/to/repo

# See what would happen, no API calls
ricord init --dry-run

# Generate summaries to disk only (review before ingest)
ricord init --no-ingest

# Optional: polish each summary with Gemini 2.5 Flash before POST
GOOGLE_API_KEY=... ricord init --llm-rewrite

By default the bundle text is shipped directly — Ricord's server-side extraction does the entity / edge work. Cost for a typical small-to-medium repo is around $0.15–0.20 in server-side credits. Re-runs are idempotent: a content-hash cache at <root>/.ricord-cache/ skips unchanged directories.

After ingest, query your graph:

• ricord_search (MCP tool, or POST /v1/search) for hybrid recall
• POST /v1/kb/global-query for GraphRAG map-reduce questions ("What's the architecture?")
• The Ricord dashboard at ricord.ai/dashboard for the visual graph

Hooks (opt-in)

Ricord ships two Claude Code hook scripts in dist/hooks/. Hooks are opt-in — installing the npm package does not activate them. You wire them into your project's .claude/settings.json yourself.

Available hooks

SessionStart — injects a compact memory digest at the start of every Claude session. Adds top SOPs, preferences, recent activity, and open tasks to the system prompt.

PreToolUse — blocks any Write, Edit, or MultiEdit call whose file_path targets MEMORY.md or the Claude auto-memory paths (.claude/projects/*/memory/*, .ricord/memory/*). Prevents the AI from silently overwriting your memory files instead of saving knowledge through the Ricord API.

Wiring hooks into Claude Code

Add this to your project's .claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "type": "command",
        "command": "node node_modules/ricord-mcp/dist/hooks/session-start.js"
      }
    ],
    "PreToolUse": [
      {
        "type": "command",
        "matcher": "Write|Edit|MultiEdit",
        "command": "node node_modules/ricord-mcp/dist/hooks/pre-tool-use.js"
      }
    ]
  }
}

Or, if you installed globally (npm install -g ricord-mcp), replace the node node_modules/... path with the global install path (e.g. $(npm root -g)/ricord-mcp/dist/hooks/session-start.js).

Note: both hooks require that RICORD_API_KEY is set in your environment (or that ~/.ricord/credentials.json exists from ricord login).

License

MIT