gitmem

Memoria persistente y revisable para tus agentes de IA: en un repositorio git que puedes leer, inspeccionar con git diff y git blame.

Tu agente de programación lo olvida todo entre sesiones. gitmem le proporciona un registro de eventos de solo adición con hechos, decisiones y correcciones, almacenado como JSONL simple en git, con proyecciones deterministas: un brief con presupuesto de tokens para inyectar en el contexto, una vista de los hechos actuales y una cola de conflictos que expone las contradicciones en lugar de sobrescribirlas en silencio.

Sin almacén vectorial. Sin llamadas a LLM. Sin servidor. Un sistema de memoria que puedes recorrer con git log.

Instalación

Instala desde npm:

npm install -g @josephy02/gitmem

O, si estás desarrollando o configurando el plugin de Claude Code, clona el repositorio e instálalo localmente:

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

Verifica la instalación:

gitmem --help

Related MCP server: palinode

Inicio rápido en 60 segundos

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

O explora la demo incluida: 45 eventos realistas con correcciones, una retractación, una promoción y un conflicto en vivo:

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

Cómo funciona

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. El registro es la única fuente de verdad. Un evento por línea en log/YYYY/MM/DD.jsonl. Nada se modifica ni se elimina: las correcciones y las retractaciones son eventos nuevos que sustituyen a los antiguos, de modo que la trazabilidad siempre se puede reconstruir (gitmem trace <id>).

2. Las proyecciones son funciones puras del registro. facts.json (valores actuales con estado live/superseded/retracted/expired/contested), brief.md (el núcleo siempre inyectado, con un límite estricto de 1.500 tokens y las decisiones primero), conflicts.json, stats.json. gitmem rebuild es byte a byte idéntico a una compilación incremental; eso es una prueba.

3. Los conflictos se exponen, nunca se auto-resuelven. Las heurísticas deterministas (correcciones divergentes, parejas de negaciones, divergencias sobre el mismo sujeto) marcan las contradicciones; ambas partes se devuelven juntas como contested. La resolución es un acto humano: escribe una corrección que se imponga a las perdedoras.

4. El ámbito se controla en un único punto de control. Cada ruta de lectura (búsqueda, consulta directa, brief, trace) pasa por una única función con comprobación de capacidades. Segment-aware: team/core otorga team/core/auth, pero nunca team/core-secrets. Las promociones cambian el alcance efectivo de un hecho y el control de acceso sigue el alcance efectivo; estrechar el alcance lo reduce de verdad.

5. Nativo de Git de verdad. gitmem init instala un controlador de mezcla en modo unión: dos ramas que añaden al mismo archivo diario se fusionan automáticamente —unión de líneas, ordenadas por ULID, siempre correcta porque los eventos son inmutables—. gitmem verify detecta ids duplicados procedentes de mezclas incorrectas.

Formato de evento

El formato es el producto. Un objeto JSON por línea, esquema en schema/memevent.schema.json: cualquier lenguaje puede escribir eventos sin esta biblioteca:

{"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}

Cinco tipos de eventos: observation, decision, correction, retraction, promotion (los cambios de alcance también son eventos: compartir tiene procedencia).

Biblioteca

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

Compromisos de diseño

• Sin LLM en la ruta de escritura. Los escritos son baratos, sin pérdidas y síncronos.

• Sin deduplicación en el momento de escribir. Las contradicciones se parecen a cuasi duplicados; un filtro en la escritura rechazaría justo los eventos que el detector de conflictos necesita ver. Todo se admite; la resolución ocurre en el momento de la proyección.

• brief.override.md — un archivo de autoría humana que siempre gana la parte superior del brief.

• Almacenamiento ante los humanos. git diff a un cambio de memoria. git blame a un hecho. Revisa la memoria de un agente en un PR.

Plugin de Claude Code

La forma más rápida de dar memoria persistente a Claude Code. Este repositorio es un marketplace de plugins:

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

(Requiere el CLI de gitmem: npm install -g @josephy02/gitmem.)

Lo que obtienes:

• Memory brief al inicio de sesión — un hook de SessionStart inyecta gitmem brief en el contexto, de modo que cada sesión empieza conociendo las decisiones y los hechos de tu proyecto. ¿No hay raíz de gitmem en el proyecto? El hook no hace nada, sin avisar.

• Herramientas de memoria en MCP — Claude puede añadir observaciones, decisiones y correcciones mientras trabaja. La raíz se detecta automáticamente ($GITMEM_ROOT, ./.gitmem, ./memory, ./.memory) y se inicializa automáticamente el primer uso.

• /remember <fact> — guarda un hecho o decisión duradera, con semántica de corrección cuando contradice una memoria existente. /remember sin argumentos aprovecha la conversación actual.

• /memory-review — recorre la cola de conflictos y las anclas obsoletas, y resuélvelas a través del registro.

Servidor MCP

Dale a cualquier cliente MCP (Claude Code, Claude Desktop, cualquier cosa que hable MCP) memoria persistente en una sola línea:

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

Expone cinco herramientas mediante stdio: memory_append, memory_brief, memory_facts, memory_conflicts, memory_trace. Las adiciones se atribuyen a agent:mcp por defecto (--author para cambiarlas); las lecturas pasan por el mismo punto de control de capacidades que todo lo demás.

Obsolescencia anclada a Git

Un hecho puede anclarse al código mediante meta.source_uri (por ejemplo, "src/auth.ts#validate_token"). Como el registro vive en git junto al código, la detección de obsolescencia es solo un 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

Sin embeddings, sin LLM y sin índice que mantener: la misma propiedad que hace revisable la memoria hace que se invalide a sí misma.

API

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

Rendimiento: la proyección completa de un registro de 10.000 eventos se ejecuta en ~50ms.

Licencia

MIT