Mycorrhiza-MCP: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

Reference implementation of Layer 1 of the Mycorrhiza proposal: a local MCP server that gives any MCP client (Claude Desktop, Cursor, Continue, …) persistent memory backed by a SHA-256 hash chain stored in SQLite. Three tools exposed: remember, recall, chain_status. See README.md for the conceptual framing and v0.2/v1.0 roadmap (cristalização, herança ativa).

Commands

Local dev setup:

python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Run the server (stdio, what an MCP client invokes):

python -m mycorrhiza.server
# or, after install:
mycorrhiza-mcp

Inspect tools interactively (FastMCP dev inspector, ships with mcp[cli]):

mcp dev mycorrhiza/server.py

Use an isolated chain for experiments — point MYCORRHIZA_DB at a throwaway path so you don't pollute the user's real chain at ~/.mycorrhiza/chain.db:

MYCORRHIZA_DB=/tmp/test-chain.db python -m mycorrhiza.server

No test suite, linter, or CI is configured. Don't fabricate commands; if you add tooling, wire it through pyproject.toml.

Architecture

Single module: mycorrhiza/server.py. Roughly four layers, top to bottom:

1. Storage path resolution — DB_PATH from MYCORRHIZA_DB env or ~/.mycorrhiza/chain.db; parent dir auto-created. State is local-only, no network, no auth.
2. Hash function — _compute_hash(seq, ts, prev_hash, content, tags) serializes a JSON object with sort_keys=True, ensure_ascii=False and SHA-256s it. Field order/serialization is the integrity contract: any change breaks chain_status retroactively.
3. Schema bootstrap — _init_db() creates the single chain table (seq PK, ts, prev_hash, content, tags as JSON-encoded array, hash UNIQUE) and an index on ts DESC. Idempotent, called at import time.
4. MCP tools (@mcp.tool() on a FastMCP("mycorrhiza") instance):
   • remember — reads tail link, computes next link's hash chained on prev's hash, inserts. Genesis sentinel for the first link is the literal string "genesis".
   • recall — SELECT … WHERE content LIKE ? AND tags LIKE ? with case-insensitive substring match; tag filter is a textual %"tag"% over the JSON array (good enough for Layer 1, swap if scale demands).
   • chain_status — walks the chain from seq=1, recomputes each hash, and verifies both prev_hash linkage and stored-hash integrity. Reports first break.