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.