gitmem

AI 에이전트를 위한 영구적이고 검토 가능한 메모리 — 읽고, diff 하고, blame 할 수 있는 git 저장소에 저장됩니다.

코딩 에이전트는 세션 사이에 모든 것을 잊어버립니다. gitmem은 사실, 결정, 수정에 대한 append-only 이벤트 로그를 제공하며, git에 일반 JSONL로 저장되고 결정적 프로젝션을 갖습니다. 컨텍스트에 주입할 토큰 예산이 책정된 brief, 최신 사실 뷰, 그리고 모순을 조용히 덮어쓰지 않도록 표면화하는 충돌 큐까지 제공합니다.

벡터 저장소도, LLM 호출도, 서버도 없습니다. git log로 확인할 수 있는 메모리 시스템입니다.

설치

npm에서 설치:

npm install -g @josephy02/gitmem

또는 Claude Code 플러그인을 개발하거나 설정하는 경우, 저장소를 clone해서 로컬에 설치하세요:

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에 이벤트당 한 줄씩 기록됩니다. 어떤 것도 변경되거나 삭제되지 않습니다 — 수정과 철회는 기존 것을 대체하는 새로운 이벤트이며, 그래서 출처(provenance)는 항상 재구성할 수 있습니다 (gitmem trace <id>).

2. 프로젝션은 로그의 순수 함수입니다. facts.json (live/superseded/retracted/expired/contested 상태의 현재 값), brief.md (항상 주입되는 코어로, 1,500 토큰 상한, 결정 우선), conflicts.json, stats.json. gitmem rebuild는 증분 빌드와 바이트 단위로 동일한 결과를 만듭니다 — 그 자체가 테스트입니다.

3. 충돌은 표면화되며, 자동으로 해결되지 않습니다. 결정적 휴리스틱(분기되는 사정, 부정 쌍, 같은 주제 분기)이 모순을 찾아내고, 양쪽 모두를 묶어 contested로 반환합니다. 해결은 사람이 하는 행동입니다: 패배한 쪽을 대체하는 수정 사항을 작성하세요.

4. 범위(scope)는 하나의 병목 지점에서 강제됩니다. search, point-get, brief, trace 등 모든 읽기 경로가 하나의 기능 검사 함수를 거칩니다. 세그먼트 인식입니다: team/core는 team/core/auth를 허용하지만 team/core-secrets는 허용하지 않습니다. 승격은 사실의 유효(effective) 범위를 바꾸고, 접근 제어는 그 유효 범위를 따라가므로, 좁히는 경우 실제로 좁아집니다.

5. 진짜 Git-네이티브입니다. gitmem init은 union merge 드라이버를 설치합니다. 두 브랜치가 같은 day file에 이어쓰면 자동 병합됩니다 — 줄들의 합집합을 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이 없습니다. 쓰기는 저렴하고, 무손실이며, 동기식입니다.

• 쓰기 시 중복 제거가 없습니다. 모순인 것처럼 이는 중복처럼 보일 수 있습니다. 만약 쓰기 시점에 게이트를 만들면 존재하지 않는 모순 검출에 필요한 그 이벤트를 거부하게 됩니다. 모든 것은 받아들여지고, 해석은 프로젝션 시점에 이뤄집니다.

• break.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가 작업하면서 관찰, 결정, 수정 사항을 추가할 수 있습니다. 루트는 자동 감지($GITMEM_ROOT, ./.gitmem, ./memory, ./.memory)되며, 첫 사용 시 자동으로 초기화됩니다.

• /remember <fact> — 지속적인 사실이나 결정을 저장합니다. 기존 메모리와 만이 될 때는 수정 의미론(correction semantics)을 따릅니다. 인자를 주지 않고 /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 이벤트 로그의 전체 프로젝션은 약 ~50ms 안에 실행됩니다.

라이선스

MIT