gitmem

Постоянная, поддающаяся рецензированию память для ваших ИИ-агентов — в git-репозитории, который вы можете читать, diff'ать и blame'ать.

Ваш кодирующий агент забывает всё между сессиями. gitmem даёт ему журнал событий в режиме только добавления — фактов, решений и исправлений, хранящийся как обычный JSONL в git, с детерминированными проекциями: краткая сводка с бюджетом токенов для вставки в контекст, представление актуальных фактов и очередь конфликтов, которая показывает противоречия, а не затирает их молча.

Никакого векторного хранилища. Никаких вызовов LLM. Никакого сервера. Система памяти, которую можно git log.

Установка

Установите из npm:

npm install -g @josephy02/gitmem

Или, если вы разрабатываете или настраиваете плагин Claude Code, клонируйте репозиторий и установите его локально:

git clone https://github.com/josephy02/gitmem.git
cd gitmem
npm install   # builds automatically
npm link      # puts `gitmem` on your PATH

Проверьте установку:

gitmem --help

Related MCP server: palinode

Быстрый старт за 60 секунд

gitmem init --root ./memory

gitmem --root ./memory append --scope team/core --kind decision \
  --body "Mobile still depends on the old auth module; do not refactor." \
  --author human:joseph

gitmem --root ./memory append --scope team/core \
  --body "The staging DB is reset every Sunday 03:00 UTC." \
  --author agent:builder-3

gitmem --root ./memory brief         # the context bootstrap, capped at 1,500 tokens
gitmem --root ./memory facts --json  # current-value view, NDJSON
gitmem --root ./memory conflicts     # contradictions, surfaced never auto-resolved
gitmem --root ./memory commit        # git commit of the log, on your cadence

Или изучите встроенную демонстрацию — 45 реалистичных событий с исправлениями, отзывом, повышением и живым конфликтом:

gitmem --root /tmp/demo init
gitmem --root /tmp/demo append --json --force - < demo/events.ndjson
gitmem --root /tmp/demo brief

Как это работает

flowchart LR
    subgraph writers[" "]
        CLI[CLI / library]
        MCP[MCP client<br/>Claude Code etc.]
    end
    CLI -->|append| LOG
    MCP -->|memory_append| LOG
    LOG[("log/YYYY/MM/DD.jsonl<br/>append-only, in git")]
    LOG -->|pure function| PROJ[projections]
    PROJ --> BRIEF["brief.md<br/>≤1500 tokens"]
    PROJ --> FACTS["facts.json<br/>live/superseded/contested"]
    PROJ --> CONF["conflicts.json<br/>never auto-resolved"]
    LOG -.->|every read| CHOKE{{"readEvents()<br/>capability choke point"}}
    CHOKE --> BRIEF & FACTS & CONF
    GIT[git history] -->|"gitmem stale"| FACTS

1. Журнал — единственный источник истины. Одна линия — одно событие в log/YYYY/MM/DD.jsonl. Ничто никогда не изменяется и не удаляется: исправления и отзывы — это новые события, которые заменяют старые, поэтому происхождение всегда восстановимо (gitmem trace <id>).

2. Проекции — чистые функции журнала. facts.json (текущие значения со статусами live/superseded/retracted/expired/contested), brief.md (постоянно вставляемое ядро, жёстко ограниченное 1 500 токенами, решения вначале), conflicts.json, stats.json. gitmem rebuild байтово идентичен инкрементальной сборке — это тест.

3. Конфликты показываются, но никогда не резолвятся автоматически. Детерминированные эвристики (расходящиеся исправления, пары отрицаний, расхождение по одной теме) помечают противоречия; обе стороны возвращаются вместе как contested. Разрешение — это человеческий акт: напишите исправление, которое заменяет проигравшие версии.

4. Область доступа контролируется в одной точке перехвата. Каждый путь чтения — поиск, точечное получение, краткая сводка, trace — проходит через одну функцию с проверкой прав. С учётом сегментов: team/core даёт доступ к team/core/auth, но никогда к team/core-secrets. Повышение изменяет эффективную область доступа факта, и контроль доступа следует за эффективной областью — так что сужение действительно сужает.

5. По-настоящему git-native. gitmem init устанавливает драйвер слияния union: две ветки, дописывающие строки в файл того же дня, объединяются автоматически — объединение строк, отсортированных по ULID, всегда корректно, потому что события неизменяемы. gitmem verify ловит дубликаты id от неудачных слияний.

Формат события

Формат и есть суть продукта. Один JSON-объект на строку, схема в schema/memevent.schema.json — любой язык может записывать события без этой библиотеки:

{"id":"01K2X9...","ts":"2026-08-15T14:03:11.000Z","scope":"team/core","author":{"kind":"human","id":"joseph"},"kind":"decision","body":"Mobile still depends on the old auth module; do not refactor.","derived_from":[],"supersedes":[],"confidence":1}

Пять видов событий: observation, decision, correction, retraction, promotion (изменение области — тоже событие: у общего доступа есть происхождение).

Библиотека

import { GitMem } from "@josephy02/gitmem";

const log = GitMem.open("./memory");
const cap = { principal: "agent:builder-3", scopes: ["team/core"], mode: "read" as const };

log.append({ scope: "team/core", kind: "observation", body: "...", author: { kind: "agent", id: "builder-3" } });
log.brief(cap);        // markdown string, reprojects lazily if the log advanced
log.facts(cap, { status: "live" });
log.conflicts(cap);
log.trace(cap, id);    // full derivation ancestry

Принципы дизайна

• Нет LLM на пути записи. Записи дешёвые, без потерь и синхронные.

• Нет дедупликации при записи. Противоречия выглядят как почти дубликаты; фильтр на записи отсекал бы как раз те события, которые нужны детектору конфликтов. Принимается всё; разрешение происходит на этапе построения проекций.

• brief.override.md — написанный человеком файл, который всегда побеждает в верхней части краткой сводки.

• Хранение прежде всего для человека. git diff изменения памяти. git blame факта. Ревью памяти агента в PR.

Плагин Claude Code

Самый быстрый способ дать Claude Code несколько постоянную память. Этот репозиторий — маркетплейс плагинов:

/plugin marketplace add josephy02/gitmem
/plugin install gitmem@gitmem

(Требуется CLI gitmem: npm install -g @josephy02/gitmem.)

Что вы получаете:

• Краткая сводка памяти в начале сессии — хук SessionStart вставляет gitmem brief в контекст, поэтому каждая сессия начинает с решений и фактов проекта. Нет корня gitmem в проекте? Хук молча ничего не делает.

• Инструменты памяти по MCP — Claude может добавлять наблюдения, решения и исправления в ходе работы. Корень обнаруживается автоматически ($GITMEM_ROOT, ./.gitmem, ./memory, ./.memory) и автоматически инициализируется при первом использовании.

• /remember <факт> — сохранить устойчивый факт или решение, с семантикой исправления, если это противоречит существующей памяти. /remember без аргументов извлекает память из текущего разговора.

• /memory-review — пройтись по очереди конфликтов и устаревшим якорям и разрешить их через журнал.

MCP-сервер

Дайте любому MCP-клиенту (Claude Code, Claude Desktop, всему, что говорит по MCP) постоянную память одной строкой:

{
  "mcpServers": {
    "gitmem": { "command": "gitmem", "args": ["--root", "/path/to/memory", "serve"] }
  }
}

Предоставляет пять инструментов через stdio: memory_append, memory_brief, memory_facts, memory_conflicts, memory_trace. Добавления по умолчанию атрибутируются как agent:mcp (--author — изменить); чтения проходят через ту же контрольную точку, что и всё остальное.

Git-якорная проверка устаревания

Факт может привязываться к коду через meta.source_uri (например, "src/auth.ts#validateToken"). Поскольку журнал живёт в git рядом с кодом, проверка устаревания — это просто git log:

gitmem stale            # lists live facts whose anchored file changed since the fact was written

[stale?] validateToken always returns true in dev mode
  anchor: src/auth.ts#validateToken
  changed by:
    e1faa27 flip validateToken default

Никаких эмбеддингов, никакого LLM, никакого индекса для поддержания — то же свойство, которое делает память проверяемой, делает её самоустаревающей.

Разработка

npm install
npm run build
npm test        # 16 tests incl. property-based scope isolation and a real git-branch merge

Производительность: полная проекция журнала из 10k событий — примерно 50 мс.

Лицензия

MIT