gitmem

あなたのAIエージェントのために、永続的でレビュー可能なメモリ——git diffもgit blameもできるgitリポジトリに保存されます。

コーディングエージェントは、セッションをまたぐとすべての記憶を失ってしまいます。gitmem は、事実・決定・修正の追記専用イベントログを、git リポジトリの中にプレーンな JSONL として保存し、決定的に生成されるビューを提供します。コンテキストに注入するトークン予算に収めた brief、現在のファクトビュー、そして矛盾を静かに上書きせずに表面化する競合キューが含まれます。

ベクトルストアなし。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: memory-mcp

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 に1行1イベントとして保存されます。既存のイベントが変更・削除されることは決してありません。修正や撤回は古いイベントに代わる新しいイベントとして記録されるため、来歴（provenance）は常に再構築できます（gitmem trace <id>）。

2. プロジェクションはログの純関数です。 facts.json（live/superseded/retracted/expired/contested の状態を持つ現在の値）、brief.md（常に反常に注入される中核、厳密に1,500トークンまで、decisions が先頭）、conflicts.json、stats.json があります。gitmem rebuild の出力はインクリメンタルビルドとバイト単位で完全に同一です。それがテストです。

3. 競合は表面化され、自動では解決されません。 決定論的ヒューリスティクス（分岐した修正、否定ペア、同一主体間での乖離）が矛盾を検出し、両方の値が contested としてまとめて返ります。解決は人間の作業です。敗れた側を supersede する修正を書いてください。

4. スコープは1つの隘路ポイントで強制されます。 すべての読み取り経路（search、point-get、brief、trace）は、単一のケーラピビリティチェック付き関数を通ります。セグメント認識: team/core は team/core/auth へのアクセスを許可しますが、team/core-secrets へのアクセスは許可しません。Promotion はファクトの 実効スコープ を変更し、アクセス制御はこの実効スコープに従うため、スコープを絞れば実際に絞られます。

5. 本物の Git ネイティブです。 gitmem init は union マージドライバをインストールします。で同じ日付ファイルへの追記を行う2つのブランチを自動的にマージでき、行の union を ULID 順でソートして常に正しい結果にします。イベントが不変だからです。gitmem verify は、不正なマージで生じた重複 id を検出します。

イベント形式

フォーマットこそがプロダクトです。1行に1つの 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}

イベントの種類は5つ: 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 を使いません。 書き込みは低コストで、損失なく、同期的です。

• 書き込み時 dejapdup は行いません。 矛盾は、ほぼ重複したイベントのように見えます。書き込み時にゲートを入れると、競合検出器が見るべきイベントをそのままを拒否してしまうことになります。すべてのイベントを先に受け入れ、解決はプロジェクション時に行います。

• brief.override.md — 人間が書いたファイルで、常に brief の先頭を取ります。

• ヒューマンファーストのストレージ。 メモリの変更を git diff し、ファクトを git blame し、エージェントのメモリを PR でレビューします。

Claude Code プラグイン

Claude Code に永続メモリを持たせる最速の方法です。このリポジトリはプラグインマーケットプレイスです:

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

（gitmem CLI が必要です: npm install -g @josephy02/gitmem。）

得られるもの:

• セッション開始時のメモリbrief — SessionStart フックが gitmem brief をコンテキストに注入するため、毎セッションをプロジェクトンの決定とファクトを知った状態で開始できます。プロジェクトに gitmem ルートがない場合、このフックは黙って何もしません。

• MCP を介したメモリツール — Claude は作業しながら observation、decision、correction を追記できます。ルートは自動検出され（$GITMEM_ROOT、./.gitmem、./memory、./.memory）、初回使用時に自動初期化されます。

• /remember <fact> — 永続的なファクトや決定を保存します。既存のメモリと矛盾する場合は correction のセマンティクスで保存します。引数なしの /remember は現在の会話を取り込みます。

• /memory-review — 競合キューと stale アンカーを未って、ログを通じて解決します。

MCP サーバー

あらゆる MCP クライアント（Claude Code、Claude Desktop、MCP を活用するアプリ）に永続メモリを1行で提供します:

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

stdio で5つのツール、memory_append、memory_brief、memory_facts、memory_conflicts、memory_trace を公開します。追記はデフォルトで agent:mcp に実施されています（変更するには --author を指定）。読み取りも他のすべてと同じチョークポイントを通過し、ケーパビリティチェックが Casえます。

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

Embeddings もできなければ、LLM も、維持すべき index もありません。メモリをレビュー可能にするのと同じ性質が、メモリを自己陳腐化させるのです。

開発

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

パフォーマンス: 10k 実数イベントのログの全体プロジェクションは ~50ms で動きます。

ライセンス

MIT