IHMT Memory

IHMT — Infinite Hierarchical Memory Tree

Long-term memory for your AI coding agents. Tell your agent something once — a decision, how your setup works, a correction — and it remembers it in every future session, in any project, with any of your agents.

What IHMT does

• Remembers across sessions. Decisions and their reasons, your environment, your preferences, people and projects, corrections. Your agent searches the memory before answering and saves what lasts, so you stop repeating yourself.
• One memory for all your agents and models. Claude Code, Codex and opencode can share the same memory: what one saves, the others find. Tested with models from Anthropic, OpenAI, Google and Meta.
• Saves tokens. Instead of pasting your notes or re-explaining context every session, the agent retrieves only what the question needs — typically 200–900 tokens, whether the memory holds 50 entries or 50,000, because search walks a tree instead of reading everything. Honest numbers, including where it does *not* save.
• Understands time. When something changes ("I moved to Valencia", "staging is on PostgreSQL 17 now"), the old memory is kept as history, flagged OUTDATED, and searches answer with the current one first. Where you live, where you work and your stack are tracked automatically; any other correction is linked when the agent saves it with replaces. When a question is ambiguous ("Luis" — which one?), it asks instead of guessing.
• Portable. Your memory is one folder of plain text files. Copy it to another computer, back it up, or put it under version control — it works wherever you put it.
• Local, private and readable. No cloud, no database, no account: IHMT stores everything on your disk and sends nothing anywhere. (The memories your agent retrieves reach its model like any other context.) Every memory is a text file you can open, and each person who installs IHMT starts with their own, empty memory.

Compatibility. Officially supported: Claude Code. Also tested: Codex (CLI and the

ChatGPT desktop app — setup) and opencode

(setup). IHMT is a standard stdio MCP server, so any

agent that supports local MCP servers should work — GitHub Copilot, Antigravity, Cursor, Windsurf,

Gemini CLI, Claude Desktop… — and INSTALL.md knows how to configure them, but we have

not tested those yet. All of them can share one memory.

Install

Before you start

Missing Python or git? Your AI agent installs them for you (it is instructed to ask you first). Python goes in your user folder, with no administrator password, so nothing system-wide changes. On a brand-new Mac, git may need one click: Apple shows a window asking to install its command-line tools.

On a Mac, note that the python3 that comes with macOS is version 3.9, which is too old — that is why your agent may say Python is missing even though python3 exists.

You do not need administrator rights, a database, an account, or any paid service beyond your agent. Tested on macOS and Linux (Ubuntu); on Windows the instructions are included but not tested yet. Details: GUIDE.md §3.

Let your AI agent install it

Paste this into the AI agent you want to give a memory to — Claude Code, Codex and opencode are tested; GitHub Copilot, Antigravity, Cursor, Windsurf, Gemini CLI, Claude Desktop and other MCP clients should work too:

Install the IHMT memory MCP server for me from https://github.com/gonzaroman/IHMT-MEMORY — follow the instructions in its INSTALL.md.

The agent follows INSTALL.md: it downloads IHMT to ~/IHMT-MEMORY, keeps your memory in ~/.ihmt, registers the server with itself only, adds the usage instructions, and tells you what it did. Then start a new session so the memory tools load.

Using several agents? Paste the same prompt in each one, whenever you want. If IHMT is already installed — say you have used it with Claude for months and now want it in Codex — the agent finds that installation, updates it if it safely can, and connects to the same memory, so it knows what you told the others from day one.

It needs an agent that can run terminal commands or edit files; chat-only assistants in a browser cannot install anything.

Manual install

Requirements: Python 3.10+, git, and your agent's CLI.

git clone https://github.com/gonzaroman/IHMT-MEMORY.git ~/IHMT-MEMORY

cd ~/IHMT-MEMORY python3 -m venv .venv .venv/bin/pip install -r requirements-mcp.txt mkdir -p ~/.ihmt

Claude Code

claude mcp add ihmt-memory -s user -e IHMT_HOME="$HOME/.ihmt" -- "$PWD/.venv/bin/python" "$PWD/mcp_server.py"

claude mcp list # ihmt-memory … ✔ Connected

The server name must come before -e. Then append templates/memory-instructions.md to ~/.claude/CLAUDE.md.

Codex — codex mcp add ihmt-memory --env IHMT_HOME="$HOME/.ihmt" -- "$PWD/.venv/bin/python" "$PWD/mcp_server.py", then add default_tools_approval_mode = "approve" to the [mcp_servers.ihmt-memory] table in ~/.codex/config.toml (above its env table) and append the template to ~/.codex/AGENTS.md. Details.

opencode — add an "ihmt-memory" entry ("type": "local", "command": [ , ], "environment": {"IHMT_HOME": }) to the "mcp" object of ~/.config/opencode/opencode.json, and append the template to ~/.config/opencode/AGENTS.md. Details.

Windows, the project scope, the graphical setup and troubleshooting are all in the guide.

Install from PyPI (uvx)

No clone and no venv: uv downloads and runs the ihmt-memory package. The memory goes to ~/.ihmt; set IHMT_HOME to use another folder (for example, a memory you already have).

Claude Code

claude mcp add ihmt-memory -s user -- uvx ihmt-memory

claude mcp list # ihmt-memory … ✔ Connected uvx ihmt-memory --instructions >> ~/.claude/CLAUDE.md

Codex — codex mcp add ihmt-memory -- uvx ihmt-memory, add default_tools_approval_mode = "approve" to the [mcp_servers.ihmt-memory] table in ~/.codex/config.toml, and run uvx ihmt-memory --instructions >> ~/.codex/AGENTS.md.

opencode — add an "ihmt-memory" entry ("type": "local", "command": ["uvx", "ihmt-memory"]) to the "mcp" object of ~/.config/opencode/opencode.json, and run uvx ihmt-memory --instructions >> ~/.config/opencode/AGENTS.md.

The last step matters with any install: the instructions are what make the agent search before answering and save corrections. pipx install ihmt-memory works too, with ihmt-memory in place of uvx ihmt-memory.

New here? Read [`GUIDE.md`](GUIDE.md) — everyday use, step by step, with real outputs. The rest of this README is the technical reference.

---

How it works

A universal, domain-agnostic long-term memory for LLMs, stored as a recursive tree of plain files on the local disk. No vector database, no server, no third-party dependencies — Python 3.10+ and the standard library.

Instead of embedding everything into one flat index and scanning it, IHMT organizes knowledge into a tree: raw text leaves at the bottom, recursive JSON summaries above them, and a single root.json trunk at the top. A query walks that tree — root → branch → branch → leaf — so the number of files opened grows with the *depth* of the tree (≈ beam × log_B(n)), not with the amount stored.

Quick start

python3 gui.py                       # graphical interface: set up, browse, inspect

python3 init_ihmt.py # or from the terminal: create ./ihmt_memory python3 main.py demo # full walkthrough in ./demo_workspace python3 -m unittest discover -v # stdlib only; MCP tests skip without the SDK

Then use it on your own material:

python3 main.py ingest ~/notes ~/project/src/Main.java

python3 main.py consolidate --force python3 main.py search "how did we handle stock reservations" python3 main.py ask "Luis" # interactive clue loop python3 main.py conflicts # what changed over time

As a library:

from ihmt import IHMT

memory = IHMT.initialize("./workspace") memory.ingest_file("examples/InventoryService.java") memory.ingest_file("examples/journal_personal.txt") memory.flush() # close the tree up to the root

answer = memory.search("reserveStock soft hold") print(answer.best.content) # the leaf print(answer.best.path) # ['root', 'N1-software.java-…', 'L-software.java-…'] print(answer.node_reads) # how many branch files were opened

for notice in memory.notices(): print(notice) # "On 2024-03-11 you said user location = 'Madrid', but on 2026-02-03 you updated to 'Valencia'."

---

Graphical interface

python3 gui.py                       # opens a browser at 127.0.0.1

python3 gui.py --path ~/my-memory --port 8765 --no-browser

Still zero dependencies — the server is http.server from the standard library, it listens only on the loopback interface, and every /api/* call needs the random token carried in the URL it opens.

Four screens: Set up (pick the memory folder with the system dialog, create the store, choose between per-project and global registration, preview the exact command or JSON before anything is written), Explore (collapsible tree down to the stored text, with supersession notices), Diagnose (a search that reports confidence, files opened vs. total, and the descent path), and Timeline (active vs. historical values and the detected contradictions). The interface is bilingual (ES/EN) and read-only over the memory: it never deletes or edits a leaf.

---

Use it from Claude Code (MCP)

mcp_server.py exposes the tree to Claude Code as nine tools in three families: long-term memory, project indexes and session scratch memory. The core stays dependency-free; the SDK is an optional extra:

python3 -m venv .venv

.venv/bin/pip install -r requirements-mcp.txt # mcp[cli]>=2.0

For a single project, copy .mcp.json.example to that project's .mcp.json and fill in the absolute p