walnut-mcp

MCP server for walnut structured context. Read, save, and manage project context from any MCP-compatible AI agent.

Install

npx @lock-in-lab/walnut-mcp ~/world

Pass your world directory as the first argument. Defaults to ~/world if omitted. Can also be set via WALNUT_WORLD_PATH env var.

Tools

| Tool | Description | |------|-------------| | walnut_read | Read a walnut's brief pack (key, now, tasks, insights, log, capsules) | | walnut_list | List all walnuts in the world with domain, goal, phase, and health | | walnut_save | Save progress: prepend log entry, update state, manage tasks | | walnut_capture | Capture content into a capsule or the world's Inputs folder | | walnut_create | Create a new walnut with full directory structure and core files |

Configuration

Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  walnut:
    command: npx
    args:
      - -y
      - "@lock-in-lab/walnut-mcp"
      - ~/world

Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "walnut": {
      "command": "npx",
      "args": ["-y", "@lock-in-lab/walnut-mcp", "~/world"]
    }
  }
}

Cursor / Windsurf

Add @lock-in-lab/walnut-mcp to your MCP server settings with ~/world as the argument.

What is a walnut?

A walnut is a self-contained unit of context — a project, person, or life area — with identity, state, history, tasks, and knowledge. Plain markdown files on your machine. Any AI model can read them.

Learn more at walnut.world.

License

MIT

Hermes Skill (behavioral layer)

The MCP tools give your agent the ability to manage walnuts. The skill tells it when and how.

Copy to your Hermes skills directory:

cp -r node_modules/@lock-in-lab/walnut-mcp/skills/walnuts ~/.hermes/skills/

Or clone directly:

git clone https://github.com/stackwalnuts/walnut-mcp.git /tmp/walnut-mcp
cp -r /tmp/walnut-mcp/skills/walnuts ~/.hermes/skills/

The skill covers: read-before-speaking, decision stashing, save protocol, cron integration, capture routing, and visual conventions.

Built by Lock-in Lab.