ricord

Knowledge wiki for AI coding assistants — persistent memory, dense repo wikis, and a knowledge graph, all over the Model Context Protocol.

This package ships two binaries:

• ricord-mcp — the MCP server, for Claude Code / Cursor / Windsurf / VS Code
• ricord — the unified CLI: wiki authoring (ricord build, ricord push), auth (ricord login), MCP setup (ricord install <client>), and more

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

Migrating from ricord-mcp? Install ricord instead — ricord-mcp is deprecated. The ricord-mcp bin still ships in this package, so existing MCP server configs keep working unchanged.

Quick start

npx ricord install claude          # auto-write MCP config for your editor
# or:
npx ricord-mcp --setup --client claude --api-key YOUR_API_KEY

Supported clients: claude-code, claude-desktop, cursor, windsurf, vscode. Get your API key at ricord.ai/dashboard/api-keys.

Manual MCP 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"]
    }
  }
}

CLI commands

ricord build                     Author a wiki for this repo (claude as agent)
ricord push                      Sync local .ricord/pages/ to the cloud
ricord pull                      Materialize cloud pages locally
ricord sync / watch              Incremental sync; auto-push on save
ricord curate / rollup           Suggest moves+merges; drain stub backlog
ricord ingest                    Walk + POST repo to /v1/ingest/repo
ricord doctor                    Readiness check (api key, project, llm, cloud)
ricord compile                   Ingest ~/.claude/projects/*.jsonl turns
ricord login / logout / whoami   OAuth + identity
ricord install <client>          Configure Claude Code / Cursor / Windsurf / VS Code
ricord install-commands          Install /ricord-* slash commands
ricord uninstall                 Remove ricord from this system
ricord daemon install            macOS launchd auto-sync agent

Run ricord --help for the full surface.

Authoring a wiki for your repo

ricord login                     # one-time OAuth
ricord build                     # auto-derives project_id from git remote
ricord push                      # send to cloud

ricord build spawns claude as a tool-using agent that walks the repo and writes .ricord/pages/*.md — dense, self-contained essays with code references and [[wikilinks]]. The first run auto-scaffolds .ricord/ledger.json + .ricord/pages/. Override the auto-derived id with --project <id> or --team <uuid>.

For headless / scripted ingestion (no claude CLI):

ricord ingest --mode initial

Server 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

MCP tools (13)

Core memory (8)

| Tool | Description | |------|-------------| | ricord_get_context | Returns instructions, active procedures, preferences for the session | | ricord_recall | Hybrid search over the user's stored knowledge | | ricord_save | Save a fact / preference / decision / reference / anti-pattern / observation | | ricord_correct | Overwrite a memory by id | | ricord_forget | Delete a memory by id | | ricord_run_procedure | Execute a stored SOP / playbook with template variables | | ricord_usage | Tier, request count, token usage, rate limit | | ricord_graph_stats | Entity count, edge count, edge-type breakdown |

Wiki (5)

| Tool | Description | |------|-------------| | ricord_wiki_topics | The project's topic tree | | ricord_wiki_pages_for_file | Pages that describe a given file or folder path | | ricord_wiki_search | Full-text search across every wiki page | | ricord_wiki_recall | Top wiki pages with full bodies, ready to paste into context | | ricord_wiki_backlinks | Inbound + outbound page references |

Slash commands

Installed by ricord install-commands (or auto on npm install):

• /ricord-build — walk this repo and author a cultivated wiki (25-60 pages) directly to .ricord/pages/*.md — your existing Claude Code session does the work in-line, every Read/Write visible
• /ricord-save-conversation — save the current chat to your Ricord knowledge graph (extracts entities + relationships + tasks)
• /ricord-lint — Karpathy lint over the wiki (contradictions, orphans, stale claims)
• /ricord-query — ask the wiki, optionally file the answer back as a new page

The slash commands are equivalent to running the inner CLI but stay in the host agent's session — zero external API spend because the host agent IS the LLM.

Hooks (opt-in)

Two Claude Code hook scripts ship in dist/hooks/. Installing the npm package does not activate them — wire them into your project's .claude/settings.json yourself.

SessionStart — injects a compact memory digest at the start of every Claude session.

PreToolUse — blocks Write / Edit / MultiEdit calls targeting MEMORY.md or the Claude auto-memory paths (.claude/projects/*/memory/*, .ricord/memory/*).

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

Globally installed (npm install -g ricord)? Replace node node_modules/... with $(npm root -g)/ricord/dist/hooks/....

Both hooks need RICORD_API_KEY in env (or ~/.ricord/credentials.json from ricord login).

License

MIT