IHMT Memory

MCP文档知识

提供方 未标注

文档知识 未标注 未标注 社区 / 第三方 Claude DesktopClaudeCursorVS Code

AI编码代理的长期记忆,以普通本地文件树的形式存储,由Claude Code、Codex和opencode共享。

一句话选型结论

按资料字段整理

IHMT Memory 属于文档知识类 MCP 服务器,传输方式未标注,鉴权方式未标注,可直接接入 Claude Desktop、Claude、Cursor 等,没有现成安装命令,需按官方文档接入。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式未标注 鉴权未标注 部署方式未标注
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

记忆

安装与配置

未标注 未标注
上游未给出传输方式
  1. 1
    准备运行环境

    按官方文档确认运行环境(常见为 Node.js 或 Python),装好后再执行安装命令。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • 没有现成安装命令,需要按官方文档自己填启动命令和参数。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
IHMT Memory当前 未标注 未标注 未标注 无 未标注
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方未标注上游标注的维护方 未标注
分类文档知识本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式未标注远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型未标注上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

29.2 KB
来自项目仓库与上游目录的原文,未做删改

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

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.

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

New here? Read 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("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```bash
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:```bash
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
paths; Claude Code asks you to approve it on the next session there (`claude mcp list` shows it as
*Pending approval* until then):```json
{
  "mcpServers": {
    "ihmt-memory": {
      "command": "/absolute/path/to/IHMT-MEMORY/.venv/bin/python",
      "args": ["/absolute/path/to/IHMT-MEMORY/mcp_server.py"],
      "env": { "IHMT_HOME": "/absolute/path/to/IHMT-MEMORY" }
    }
  }
}

or in one command:```bash
claude mcp add ihmt-memory --scope user \
-e IHMT_HOME=/absolute/path/to/IHMT-MEMORY \
-- /absolute/path/to/IHMT-MEMORY/.venv/bin/python /absolute/path/to/IHMT-MEMORY/mcp_server.py


`IHMT_HOME` selects the store (`$IHMT_HOME/ihmt_memory`), created on first use. Point every project at
one shared directory for a single cross-project memory, or give each project its own.

| Tool | Behaviour |
|---|---|
| `search_memory(query, clue=None, detail="compact")` | Walks the tree. Compact output: the best memory with its date and `OUTDATED` notices, one line per other match; `detail="full"` adds ids, tree paths and excerpts. An ambiguous query returns an `AMBIGUOUS` block listing the candidates instead of guessing — call again with `clue`. A query that matches nothing says so, and so does one whose closest entry shares only a stray word with it (`NOT FOUND`). |
| `save_memory(content, domain="general", content_type="auto", replaces="")` | Classifies, splits and stores the text, extracts dated facts, and keeps the tree consolidated. Reports how it was filed and — if the save contradicts something remembered earlier — the notice to relay to the user. With `replaces` (a few words describing an earlier memory) the save is recorded as its correction: the old memory is flagged `OUTDATED` and searches answer with the new one first. |
| `mark_outdated(old_id, new_id)` | Flags one memory as corrected by another, when `save_memory` found several candidates for `replaces` and listed their ids. |
| `project_map(path, detail="files", subpath="")` | Compact map of a codebase: files with their size in tokens and, with `detail="symbols"`, each method with its line range. Built from the sync manifest, without opening leaves. |
| `find_code(query, path, scope="main", subpath="", clue=None, max_tokens=1500)` | Returns only the symbol that answers the query, as `file:first-last` + code. `scope` is `main` (skip tests), `test` or `all`. |
| `read_file(path, force=False)` | Reads a file and remembers what it handed out this session: a repeated read answers `UNCHANGED` or only a unified diff. |
| `note(text)` / `recall(query, clue=None)` | Session scratch memory: survives a context compaction, disappears when the session ends. |
| `digest_output(text, label="output")` | Condenses a long log to its first lines, errors, failures, test totals and last lines; the full text stays recallable. |

### Saving tokens inside a session

Long-term memory saves tokens *between* sessions. The project tools save them *within* one, where the
cost is reading the same files again and again. `ProjectIndex` (`ihmt/project_index.py`) keeps a
private store per project under `$IHMT_PROJECTS_DIR` (default `$IHMT_HOME/ihmt_projects`):

* **one leaf per symbol** — `code_chunk_mode="symbol"`, so a lookup returns a method, not a file;
* **checksum sync on every call** — size and mtime first, SHA-256 only for what moved; changed files
  are re-ingested, removed ones deleted, and the branches rebuilt. Code is never served stale;
* **path-ordered branches** — each file is stamped with its rank in path order, so every branch covers
  neighbouring files and its summary stays meaningful for the descent;
* **code-aware ranking** — the navigator filters by `scope`/`path_prefix` from the catalog, prefers
  the file a query names, demotes tests unless asked and demotes import lines.

Measured on a 55-file Spring Boot project (8 typical questions): reading the files that hold the
answers costs 3,613 tokens; `find_code` returns the exact method for all 8 in 1,071. The map of the
project costs 660 tokens against 13,157 to read it whole.

Those savings are against an agent that **reads whole files**. In an A/B test with 22 real headless
Claude Code sessions, Claude preferred batched `grep`/`sed -n` and never called the project tools on
its own; *forcing* them made sessions 42–71 % more expensive. Keeping the server enabled costs about
460 tokens per conversation, since Claude Code loads MCP tools on demand. IHMT's main value is memory
**between** sessions; treat the project tools as optional, and do not mandate them in `CLAUDE.md`.

The server transparently supports MCP SDK 2.x (`MCPServer`), 1.x (`FastMCP`) and the standalone
`fastmcp` package.

The usage instructions in your `~/.claude/CLAUDE.md` (template) tell Claude Code *when* to reach for each tool: search before answering anything that
depends on earlier sessions, save durable facts with their date, never guess on `AMBIGUOUS`, always
relay `OUTDATED`, and never store secrets.

---

## Storage layout

Everything lives in one relocatable directory:```
ihmt_memory/
  root.json                 # the trunk: domains, topics, top branches, counters
  layer_0/<domain>/*.txt    # the leaves: raw UTF-8 text + a strict JSON header
  layers/1/*.json           # branches: summaries of leaves
  layers/2..N/*.json        # branches: summaries of summaries
  state/catalog.json        # index: id -> path, domain, parent, timestamp
  state/facts.json          # the fact timeline
  ihmt.config.json          # branch factor, token budgets, backend

root.json lives inside ihmt_memory/ so the store is self-contained: copy the directory and the
memory travels with it.

A leaf is a normal text file that describes itself, so it stays meaningful even if the catalog is
lost:```
<<<IHMT-META
{
"leaf_id": "L-software.java-0001-84130ee123",
"timestamp": "2026-09-09T17:45:00Z",
"data_type": "CODE",
"domain": "software.java",
"tags": ["method:reserveStock", "class:InventoryService", "lang:java", "type:code"],
"parent_id": "N1-software.java-5571a7baac",
"span": {"start_line": 43, "end_line": 68},
"checksum": "sha256:…",
"extra": {"context": "public final class InventoryService {"}
}
IHMT-META>>>
public Optional<String> reserveStock(Sku sku, int quantity) {
…


**A branch node** embeds each child&#x27;s title, excerpt and keywords. That is the detail that makes the
descent cheap: a branch can be *ranked without opening any of its children*.

---

## The five components

### 1. `UniversalIngestor` — detect, split, enrich, store

`DomainDetector` classifies each document by **type** (`CODE`, `NARRATIVE`, `CLINICAL`, `PERSONAL`,
`PROCESS`, `GENERIC`) and **domain** (`software.java`, `medicine.clinical`, `process.cooking`,
`personal`, …) from its extension plus lexical signatures in English and Spanish. Both can be
overridden with `--domain` / `--type`.

The type selects the splitter, and every splitter obeys one invariant:

&gt; **A logical block is never cut.** If a single block exceeds `max_tokens` it is stored whole and
&gt; flagged `oversized`. Correctness of the block beats hitting the token budget.

* **Code** (`chunkers/code.py`) — Python via the stdlib `ast`; Java/JS/TS/C/C++/C#/Go/Rust/Kotlin/
  Swift/PHP via `BraceScanner`, a character-level scanner that tracks brace depth while skipping
  comments, string literals, char literals, template literals and preprocessor lines. Imports
  coalesce; each class/function is a block; an oversized class splits **per member**, and the
  enclosing class header travels in the leaf&#x27;s `extra.context` rather than being spliced into the
  text. Concatenating a file&#x27;s leaves reproduces the file **byte for byte** — asserted in the tests.
* **Narrative** — paragraph-atomic, with `***`, `---`, `Chapter`/`Capítulo` as hard boundaries. Only
  a paragraph larger than `max_tokens` is split, and then at sentence boundaries.
* **Temporal** (journals, chats, clinical records) — one dated entry is atomic and a change of date
  is a hard boundary, so a leaf never mixes two encounters. **The date found in the text becomes the
  leaf&#x27;s timestamp**, which is what makes recency weighting mean *when something was true* rather
  than when it was ingested.
* **Process** (recipes, protocols, runbooks) — steps and ingredient lists stay attached to their
  heading.

Leaf ids are derived from `(domain, source, position, content)`, so re-ingesting an unchanged
document rewrites the same leaves instead of duplicating them.

### 2. `RecursiveSummarizer` — the Summarization Event

It watches layer 0. When `branch_factor` leaves of one domain have no parent, it fires a
**Summarization Event**: they are condensed into a layer-1 node, the node is written, and *only then*
are the children stamped with their `parent_id` — so an interrupted run re-processes a group instead
of orphaning it. The same rule applies from layer 1 to layer 2, and so on, until the tree converges;
then `root.json` is rewritten.

`consolidate()` is idempotent. `flush()` (`--force`) also promotes partial groups so the tree closes
completely. Anything still unconsolidated is referenced directly by the trunk, so **nothing in the
store is ever unreachable from the root**.

### 3. `SemanticNavigator` — descent and the Interactive Clue Loop

Ranking uses Okapi BM25 over each candidate&#x27;s title, keywords, tags and excerpt, with field weights
and document frequencies computed **across the siblings of the current level** — exactly the
discrimination the descent needs, at no extra I/O cost. The walk keeps a beam of `beam_width`
branches per level.

Confidence blends two independent signals:```
confidence = 0.6 × coverage + 0.4 × margin

Coverage asks "does this leaf actually contain what was asked?"; margin asks "is it
distinguishable from its rivals?". A common first name scores high on the first and near zero on the
second — which is precisely when the system must not guess:```
$ python main.py ask "Luis"

"Luis" is ambiguous (3 memories match this query equally well, confidence 0.62).
It could belong to any of these branches:
1. [personal] journal_personal.txt · 2024-07-22 — Vacaciones en Benidorm con Luis, mi primo…
2. [personal] journal_personal.txt · 2026-08-30 — Fin de semana en la playa de El Saler con Luis…
3. [personal] journal_personal.txt · 2024-11-30 — Cierre de trimestre… Luis Marín revisó el pull request…
Give me a clue to narrow it down (e.g. a place, a date, a project):
> vacaciones en Benidorm

query: "Luis + vacaciones en Benidorm" · confidence 0.74 · 5 node reads, 3 leaf reads, depth 2
1. [personal] journal_personal.txt · 2024-07-22
path root → N2-personal-ea34db33ae → N1-personal-59bf8bc291 → L-personal-0002-a17b3c8f35


The clue triggers a **joint cross-reference**: candidates matching *both* term groups are boosted
(×1.6), candidates matching only one are demoted (×0.7). The loop runs up to `max_clue_rounds`
times, stops early if the user declines, and never silently converts an ambiguous query into a
confident answer.

`clue_provider` is any callable, so the loop works for a human at a terminal (`input`) or for an
agent that lets the LLM supply its own follow-up.

### 4. `ConflictResolver` — recency weighting and the timeline

Facts are `(subject, attribute, value, timestamp, source_leaf)`, recorded programmatically via
`record_fact()` or extracted at ingest time by pattern rules (`vivo en X` / `I live in X`,
`mi stack es Y`, `trabajo en Z`, `Diagnóstico:`, `Tratamiento:`, `Medicación:` …; extend with
`add_pattern`).

Each `(subject, attribute)` keeps a dated timeline. The newest value is `ACTIVE`; every earlier one
becomes `HISTORICAL` with `superseded_by` and a `valid_from`/`valid_to` interval. **Nothing is
deleted**, so both questions stay answerable:```python
memory.resolver.active_state()[&quot;user::location&quot;].value      # &#x27;Valencia&#x27;  (now)
memory.resolver.state_at(&quot;2024-12-31&quot;)[&quot;user::location&quot;].value  # &#x27;Madrid&#x27;  (back then)

Repeating a value at a later date is a confirmation, not a contradiction. A genuine change produces a
transparent notice — "On 2024-03-11 you said user location = 'Madrid', but on 2026-02-03 you updated to
'Valencia'."
— and the superseded leaf is annotated, so retrieving outdated material always arrives
with its correction attached (SearchResult.notices).

A leaf itself stays ACTIVE: what it says was true on its own date, and that remains the right
answer to a historical question. What changes is that it can no longer be read as current.

5. Summarization backends```python

class SummarizerBackend(Protocol):
name: str
def summarize(self, children, *, domain: str, layer: int) -> NodeSummary: ...


* `HeuristicSummarizer` (default) — stdlib extractive summarization: TF term ranking with EN/ES stop
  words plus representative-sentence selection. Offline, deterministic, which is what lets the test
  suite assert on tree shape.
* `AnthropicSummarizer` (optional) — used only when selected *and* the `anthropic` package and
  `ANTHROPIC_API_KEY` are both present. Every failure path (missing SDK, missing key, network error,
  unparseable reply) falls back to the heuristic backend, so a consolidation is never lost because a
  model was unreachable.```bash
python3 init_ihmt.py --backend anthropic     # model set by summarizer_model in ihmt.config.json

Any other model or local runtime plugs in by implementing the same protocol and passing it as
IHMT(..., backend=MyBackend()).


CLI reference

Command Purpose
init [--branch-factor N] [--target-tokens N] [--force] create the store
ingest [--domain D] [--type T] [--tag X] [--no-consolidate] ingest files, directories or stdin
consolidate [--force] run pending Summarization Events
search [--top-k N] [--full] walk the tree
ask [--clue TEXT] [--top-k N] search with the clue loop
tree [--depth N] outline of the hierarchy
stats, facts [--subject S], conflicts [--subject S] inspection
rebuild rebuild catalog, timeline and trunk from the files
demo end-to-end walkthrough

--path selects the store directory and --json emits machine-readable output; both work before or
after the subcommand.

Configuration

ihmt_memory/ihmt.config.json:

Key Default Meaning
branch_factor 8 children per branch; the log base of retrieval cost
target_tokens / max_tokens 2000 / 3000 leaf size target and oversize threshold
beam_width 3 branches kept alive per level
confidence_threshold 0.45 below this, ask for a clue
ambiguity_margin 0.18 score gap under which candidates count as tied
max_clue_rounds 3 clue-loop iterations
summarizer_backend / summarizer_model heuristic / claude-sonnet-5 summarization
code_chunk_mode pack symbol stores one leaf per class member (used by project indexes)

Small corpora deserve a small branch factor — the demo uses branch_factor=4, target_tokens=400 so a
handful of documents still builds a genuine multi-layer tree.

Tests```bash

python3 -m unittest discover -v # from the project root


187 tests — 25 of them for the MCP server, skipped without the SDK — covering: byte-exact
reconstruction and boundary-depth invariants for Java and Python, scene/date/section atomicity,
oversized-block handling, leaf header round-trips, catalog recovery, summarization thresholds, upward
propagation, idempotence, full reachability from the root, descent cost bounds, the clue loop,
recency weighting, historical preservation, the project indexes, the MCP tools, the graphical
interface and the CLI.

## Design notes and limits

* **Retrieval is a descent, not a scan.** That is the whole point, and it means a branch pruned at
  the trunk is not revisited. Domain-level pruning only happens when a query has actual signal at the
  trunk; if it has none, every domain stays in play and the beam applies one level down. The clue
  loop is the recovery mechanism when the descent goes wide.
* **Lexical, not semantic.** Matching is BM25 over accent-folded, CamelCase-split tokens: it works in
  any language and needs no model, but it will not match a synonym. Plugging an embedding re-ranker
  into `BM25Ranker` is the natural upgrade; the tree structure does not change.
* **Token counts are estimated** at ~4 characters per token. Budgets only need to be consistent, not
  exact.
* **Fact extraction is pattern-based.** The bundled rules cover common English/Spanish phrasings and
  clinical headers; `record_fact()` is the reliable path, and `add_pattern()` extends the rules.
* **Single-writer.** Writes are atomic (`tmp` + `os.replace`) and catalog rebuilds take a lock file,
  but the store assumes one writer at a time.
* `initialize(force=True)` discards *derived* state only — branches, catalog, timeline — and detaches
  the surviving leaves so the next consolidation rebuilds the hierarchy. Leaf content is never
  deleted.

## Layout```
ihmt/
  api.py                    IHMT facade wiring everything together
  config.py                 IHMTConfig
  models.py                 MemoryLeaf, BranchNode, ChildRef, RootIndex, Fact, Contradiction
  storage.py                MemoryStore: atomic I/O, catalog, recovery
  textutils.py              tokenizing, keywords, entities, extractive summary, timestamps
  detectors.py              DomainDetector
  chunkers/                 base · code · narrative · temporal · process · generic
  summarizers.py            SummarizerBackend · Heuristic · Anthropic
  universal_ingestor.py     UniversalIngestor
  recursive_summarizer.py   RecursiveSummarizer
  semantic_navigator.py     SemanticNavigator, BM25Ranker, ClueRequest, scope/path filters
  project_index.py          ProjectIndex: per-project code cache with checksum sync
  conflict_resolver.py      ConflictResolver + timeline manager
ihmt_gui/                   local graphical interface (stdlib only)
mcp_server.py               MCP server: the nine tools
ihmt_launcher.py            the `ihmt-memory` command of the PyPI package (~/.ihmt by default)
pyproject.toml · server.json   PyPI package · MCP Registry entry
init_ihmt.py · main.py · gui.py · examples/ · tests/
GUIDE.md                    installation and usage guide
INSTALL.md                  installation instructions for AI agents
templates/                  memory-instructions.md: the usage rules agents append to CLAUDE.md / AGENTS.md

License

MIT © 2026 Gonzalo Román Márquez (gonzaroman)

常见问题

6 问
答案由本站依据条目字段整理,不引用上游原文
IHMT Memory 怎么安装?

资料没有给出安装命令,请到官方仓库或文档按说明接入;这类条目多数是生态应用,或尚未发布可安装包。

IHMT Memory 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

IHMT Memory 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

IHMT Memory 需要 API Key 吗?

资料没有标注鉴权方式,是否需要密钥取决于服务本身,接入前按官方文档确认。

IHMT Memory 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、VS Code、Windsurf、Cline;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

IHMT Memory 能提供哪些能力?

资料显示能力标签包括 记忆。具体工具清单以官方文档为准。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。