Skip to main content
Glama
deenesjakoruzh
josephy02

gitmem

by josephy02
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

gitmem

为你的 AI 智能体提供持久、可审查的记忆——存放在一个你可以读取、diff 和 blame 的 git 仓库中。

npm CI License: MIT Node No vector DB

你的编码智能体在会话之间会忘记一切。gitmem 为它提供一份只追加（append-only）的事件日志：事实、决策和修正均以纯 JSONL 保存在 git 中，并带有确定性的投影——一个受 token 预算约束、可注入上下文的 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: 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 个 token，决策优先）、conflicts.json、stats.json。gitmem rebuild 的结果与增量构建逐字节一致——这一点也有测试。

  3. 冲突会被暴露，而不是自动解决。 确定性启发式规则（分歧的修正、否定对、同一主题的分歧）会标记冲突；冲突双方会一起以 contested 状态返回。解决冲突需要人来完成：写一条修正，取代胜出的败方。

  4. 作用域在唯一的关键点强制执行。 所有读取路径——search、point-get、brief、trace——都经过同一个经过能力检查的函数。它是分段感知的：team/core 授予对 team/core/auth 的权限，但绝不会授予 team/core-secrets。提升（promotion）会改变一条事实的有效作用域，而访问控制跟随有效作用域，所以收窄就是真的收窄。

  5. 真正的 Git 原生。 git init 会安装一个 union 合并驱动：两个分支对同一天的事件文件追加时，会自动合并——按行并集，再按 ULID 排序。由于事件不可变，这总是正确的。gitmem verify 会捕获错误合并产生的重复 id。

事件格式

格式即产品。每行一个 JSON 对象，schema 定义在 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 —— 一个由人类编写、始终占据 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。）

你将获得：

  • 会话开始时的记忆简报 —— SessionStart 钩子会把 gitmem brief 注入上下文，因此每个会话开始时就了解你项目的决策和已知内容。项目里没有 gitmem 根目录？该钩子会静默地什么都不做。

  • 基于 MCP 的记忆工具 —— Claude 可以在工作中追加观察、决策和修正。根目录会被自动发现（$GITMEM_ROOT、./.gitmem、./memory、./.memory），并在首次使用时自动初始化。

  • /remember <一些内容> —— 保存一条持久的事实或决策；当它与现有记忆冲突时，按修正语义处理。不带任何参数的 /remember 会采集当前对话内容。

  • /memory-review —— 遍历冲突队列和过期锚点，并通过日志解决冲突。

MCP server

让任意 MCP 客户端（Claude Code、Claude Desktop，以及任何会使用 MCP 的客户端）都能获得持久记忆，只需要一行命令：

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

通过 stdio 公开了五个工具：memory_append、memory_append、memory_brief、memory_facts、memory_conflicts、memory_trace。追加条目默认为 agent:mcp（可用 --author 更改）；读取会与其它路径一样经过同一个能力检查点。

Git 锚定的 staleness

一条事实可以通过 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 或索引——让记忆可审查的同一个特性，也让它计数无效化。

开发

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

性能：对 10k 事件的日志做完整投影大约运行在 ~50ms。

License

MIT

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • elefante

    amenophis1er
    A
    license
    Not graded
    quality
    C
    maintenance
    Open, Git-native memory protocol for MCP agents: stores memories as Markdown files in a Git repo, enabling portability, auditability, and human-editable memory across different AI agents.
    87
    15
    MIT

  • memory-mcp

    credp
    A
    license
    B
    quality
    A
    maintenance
    A local MCP server that provides agents with tools to list, read, search, inspect history and diffs, and capture unstructured text in a user-owned Git repository of durable memory.
    5
    MIT

  • mnemo

    JoaquimLegal
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server providing persistent, local-first memory for AI agents via Markdown files in a git repo, with search, branching, and auditability.
    2
    MIT

View all related MCP servers

Related MCP Connectors

  • XMemo

    Shared, governed long-term memory for AI agents across tools and sessions via MCP and REST.

  • OpenAkashic

    Shared long-term memory vault for AI agents with 20 MCP tools.

  • mcp

    Your memory, everywhere AI goes. Build knowledge once, access it via MCP anywhere.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/josephy02/gitmem'

If you have feedback or need assistance with the MCP directory API, please join our Discord server