IHMT-MEMORY

# IHMT — Infinite Hierarchical Memory Tree

[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/gonzaroman/ihmt-memory)

<!-- mcp-name: io.github.gonzaroman/ihmt-memory -->

**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](GUIDE.md#11-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](GUIDE.md#56-using-it-with-codex-tested)) and **opencode**
> ([setup](GUIDE.md#57-using-it-with-opencode-tested)). 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`](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

| You need | Why |
|---|---|
| **Python 3.10 or newer** | IHMT is written in Python |
| **git** | to download IHMT and keep it updated |
| **An AI agent that can run commands** (Claude Code, Codex, opencode, Copilot in agent mode…) | it installs IHMT and then uses the memory |
| **Internet, during the installation** | to download the code and the MCP package; not needed afterwards |

**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](GUIDE.md#3-requirements).

### 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`](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.

<details>
<summary><b>Manual install</b></summary>

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

```bash
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**

```bash
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`](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](GUIDE.md#56-using-it-with-codex-tested).

**opencode** — add an `"ihmt-memory"` entry (`"type": "local"`, `"command": [<python>, <mcp_server.py>]`,
`"environment": {"IHMT_HOME": <memory folder>}`) to the `"mcp"` object of
`~/.config/opencode/opencode.json`, and append the template to `~/.config/opencode/AGENTS.md`.
[Details](GUIDE.md#57-using-it-with-opencode-tested).

Windows, the project scope, the graphical setup and troubleshooting are all in the
[guide](GUIDE.md#4-installation-step-by-step).

</details>

<details>
<summary><b>Install from PyPI (uvx)</b></summary>

No clone and no venv: [uv](https://docs.astral.sh/uv/) downloads and runs the
[`ihmt-memory`](https://pypi.org/project/ihmt-memory/) package. The memory goes to `~/.ihmt`; set
`IHMT_HOME` to use another folder (for example, a memory you already have).

**Claude Code**

```bash
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`.

</details>

**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.

| | Flat RAG | IHMT |
|---|---|---|
| Retrieval cost | scan / ANN over all *n* chunks | `beam × log_B(n)` file reads |
| Structure | none — a bag of vectors | explicit hierarchy, inspectable |
| Chunking | fixed character windows | syntax-, scene- and date-aware |
| Stale facts | served silently | superseded, dated, and flagged |
| Ambiguity | returns a plausible guess | asks you for a clue |
| Storage | binary index | UTF-8 `.txt` + JSON you can read |

## Quick start

```bash
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:

```bash
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:

```python
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("