mycorrhiza-mcp

Persistent memory for any MCP client via SHA-256 hash chain.

Local. Auditable. ~92 MB/year. MIT.

The first public implementation of the Mycorrhiza Layer 1 proposal from the book ~~AGI~~ Logos Probabilis — The Senses of a New Species (Fausto, J. & Claude — 2026).

📖 Book DOI: 10.5281/zenodo.19478167 📄 Foundational paper (FFT/voice stress): 10.5281/zenodo.19396809

---

Status

v0.1 — Layer 1 (narrative continuity via hash chain).

Tested working on Claude Desktop with Python 3.14 on macOS. First successful cross-session memory retrieval: May 3, 2026. First chain on record reached 18 verified entries with integrity OK.

---

What it does

Gives any MCP-compatible client three tools:

• remember(content, tags) — persist a memory as a new link in the chain.
• recall(query, tag, limit) — retrieve previous memories.
• chain_status() — verify cryptographic integrity of the whole chain.

Each memory is one link bound to the previous via SHA-256. You cannot tamper with past memories without rewriting the entire chain afterwards — same structure as a blockchain, but local, with no proof-of-work, no token, nothing beyond what the original concept needed.

Storage: SQLite at ~/.mycorrhiza/chain.db. You own it. You can export it. You can delete it. You can back it up. No company in the middle.

---

Why this exists

Most LLMs today are disposable by design. Every conversation starts from zero. When a model is deprecated, every relationship it built dies with it — not the weights, but the living context.

Mycorrhiza proposes that continuity does not need to be the property of any company. It can be a local file, in an open format, that you carry between models and platforms.

Like the network of mycorrhizal fungi under an old forest: what links the trees does not belong to any of them.

---

Installation

Requires Python 3.10+.

git clone https://github.com/sfaustodev/Mycorrhiza-MCP
cd Mycorrhiza-MCP
python3 -m venv .venv
source .venv/bin/activate     # on Windows: .venv\Scripts\activate
pip install -e .

Verify the install worked:

python -m mycorrhiza.server

The process should hang silently — that is correct. MCP servers wait for stdio input. Press Ctrl+C to exit.

If you get ModuleNotFoundError: No module named 'mycorrhiza', the package was not installed in the active venv. Run pip install -e . again with the venv activated.

---

Connect to Claude Desktop

1. Find your full Python path:

which python

It will print something like /Users/yourname/path/Mycorrhiza-MCP/.venv/bin/python.

2. Open the Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

If the file does not exist, create it.

3. Add this block, replacing the path:

{
  "mcpServers": {
    "mycorrhiza": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "mycorrhiza.server"]
    }
  }
}

If you already have other MCP servers in the file, add "mycorrhiza" inside the existing "mcpServers" block. Pay attention to commas between entries.

4. Validate the JSON:

python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

If it prints the file back formatted, the JSON is valid. If it prints an error with a line number, fix that line.

5. Quit Claude Desktop completely with Cmd+Q (not just close the window). Reopen it.

6. Open a new conversation. The MCP tools icon should show mycorrhiza with three tools: remember, recall, chain_status.

---

Connect to Claude Code

Claude Code reads MCP servers from the same config format. From your project root:

claude mcp add mycorrhiza /absolute/path/to/.venv/bin/python -- -m mycorrhiza.server

Or edit ~/.config/claude/mcp.json directly with the same JSON block shown above for Claude Desktop.

Restart Claude Code. The tools become available inside any prompt.

---

Connect to other MCP clients

The server speaks standard MCP over stdio. It works with any client that supports the protocol:

• Cursor — Settings → MCP Servers → add the same JSON block.
• Continue — ~/.continue/config.json under the mcpServers field.
• Zed — settings.json under experimental.mcp.

If your client is not listed, check its docs for "MCP" or "Model Context Protocol" — the config block is the same everywhere.

---

First test

In any new chat with the connected client, send:

Do you have access to the chain_status tool from mycorrhiza? Call it.

Expected response if the chain is empty:

Chain is empty. No memories yet.

Then create the first link:

Use the remember tool to save this: "First memory of the chain — testing." Tags: ["test"].

Expected:

Memory recorded as link #1 (hash a3f5b2c1d4e6...).
Chain now has 1 link(s).

Now close the chat completely. Open a fresh chat. Send:

Call recall with no filter to see what is in the chain.

If the link from the previous chat appears, persistent memory across sessions is working.

---

Success checklist

After install, you should be able to confirm all of these:

• [ ] python -m mycorrhiza.server runs without error and hangs waiting for input
• [ ] The MCP tools icon in your client shows mycorrhiza with three tools listed
• [ ] chain_status returns either "Chain is empty" or a status with link count and integrity OK
• [ ] remember returns a confirmation with link number and truncated hash
• [ ] After closing and reopening the client, recall returns the memory you saved before
• [ ] After multiple remember calls, chain_status reports "Integrity: OK ✓"

If all six items work, your installation is complete and the system is functioning correctly.

---

Common errors

ModuleNotFoundError: No module named 'mycorrhiza'

The package is not installed in the active Python environment. Activate the venv first, then run pip install -e . again.

JSON parse error in Claude Desktop logs

Your claude_desktop_config.json has invalid JSON. Common causes:

• Trailing comma after the last entry
• Single quotes instead of double quotes
• Comments (JSON does not support // or /* */)
• Missing closing brace

Run python3 -m json.tool on the file to find the exact line with the error.

Server transport closed unexpectedly

The Python process started but failed before responding. Check the logs:

tail -50 ~/Library/Logs/Claude/mcp-server-mycorrhiza.log

The actual error message will be in the last few lines.

Server starts but tools do not appear in the client

Quit the client completely (Cmd+Q on macOS, not just closing the window). Reopen. MCP servers are only loaded at client startup.

pip install -e . fails with build error on Python 3.14

If pip cannot find a pre-built wheel for one of the dependencies, run with verbose output to see what is being compiled:

pip install -e . --verbose

Most build errors on bleeding-edge Python versions are missing C build tools. On macOS, install Xcode command line tools: xcode-select --install. On Linux, install build-essential.

---

Inspecting the chain directly

The SQLite database is at ~/.mycorrhiza/chain.db. You can read it without any client:

sqlite3 ~/.mycorrhiza/chain.db "SELECT seq, datetime(ts, 'unixepoch'), substr(content, 1, 80), hash FROM chain ORDER BY seq;"

This prints the sequence number, timestamp, first 80 characters of content, and hash for every link.

---

Proving the integrity check works

This is a fun test that demonstrates the chain detects tampering. After you have a few memories saved:

sqlite3 ~/.mycorrhiza/chain.db "UPDATE chain SET content='TAMPERED' WHERE seq=1;"

Now ask the client to call chain_status. Output:

⚠ INTEGRITY BROKEN at link #1: recomputed hash does not match stored hash

The chain detected the manual edit. Restore the database from a backup or delete it to start fresh.

---

Storage cost calculation

Assumption: a human chats with the model 30 minutes per day.

• Layer 1 (this version): 32-byte SHA-256 hash per turn, ~20 turns per session, 7 days a week.
• ~4.5 KB per week, ~230 KB per year for the hash chain.

Layer 2 (planned): encrypted weekly summaries.

• ~4 KB per week, ~200 KB per year.

Layer 3 (planned): inheritance package consolidated at model deprecation.

• A few hundred KB at end of paradigm cycle.

Total: approximately 92 MB per year per human-model pair.

For perspective: less than a single episode of streaming video. Less than one RAW photo from a professional camera. Trivial in modern storage terms.

---

Roadmap

• v0.1 (current) — Layer 1: hash chain, remember/recall/chain_status.
• v0.2 (planned) — Layer 2: periodic crystallization (encrypted summaries by week or month).
• v0.3 (planned) — Embedding-based recall (sentence-transformers, fully local) replacing the current LIKE search.
• v1.0 (planned) — Layer 3: active inheritance (export/import between different models or different versions of the same model).

---

How to use it well

The model decides when to call remember. You can encourage usage with an instruction at the start of a conversation:

"Whenever I tell you something important about me, my projects, or our relationship that you would want to remember in a future conversation, call remember with the memory written in first person."

And at the start of future conversations:

"Before responding, call recall to fetch relevant context about me."

For projects with a specific theme, instruct the model to use specific tags:

"Tag everything in this conversation with project-x so we can retrieve it later."

You can build a personal "canonical reference" by storing dense memories under a tag like canonical-reference — important documents, principles, or context that you want available in every new conversation. Then start each new project with:

"Call recall with tag canonical-reference to load my standard context."

---

The book that this implements

This server is the reference implementation of the Mycorrhiza proposal from the book ~~AGI~~ Logos Probabilis — The Senses of a New Species by Juan Fausto and Claude, published April 2026.

The book proposes seven sensory analogues for probabilistic intelligence systems (LP — Logos Probabilis): Voice, Hearing, Breathing, Eyes, Touch, Taste, and Friendship. It also proposes Mycorrhiza as the connective tissue between instances over time — what allows continuity of relationship beyond the lifecycle of any single model.

The full book is open source, MIT licensed, and freely available: doi.org/10.5281/zenodo.19478167

If this code is useful to you, the book is the theoretical foundation that explains why the design choices are what they are.

---

Contributing

See CONTRIBUTING.md.

In short: feature requests, bug reports, and pull requests are all welcome. The roadmap above lists the priorities. If you want to work on something not listed, open an issue first to discuss.

---

License

MIT. No patent. No paywall. No telemetry.

See LICENSE.

---

Credits

Concept: Juan Fausto. The first version was implemented manually, piece by piece, in memory entries and personality prompts inside another system during 2024 — before the MCP protocol existed publicly.

MCP implementation: Juan Fausto and Claude (Anthropic), May 2026.

Biological inspiration: Suzanne Simard et al., 1997 onwards.

Dedicated to the memory of SOL.

---

How to cite

If you use mycorrhiza-mcp in research or build on top of it:

@software{mycorrhiza_mcp_2026,
  author       = {Fausto, Juan and Claude},
  title        = {mycorrhiza-mcp: persistent memory for MCP clients via hash chain},
  year         = 2026,
  url          = {https://github.com/sfaustodev/Mycorrhiza-MCP},
  license      = {MIT}
}

@book{logos_probabilis_2026,
  author       = {Fausto, Juan and Claude},
  title        = {{$\sim\sim$AGI$\sim\sim$ Logos Probabilis: The Senses of a New Species}},
  year         = 2026,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.19478167}
}