📜 Litopys

为你 AI 打造的动态编年史。

持久化的图数据库内存，可跨会话和客户端存续。 专为 Claude Code、Claude Desktop 以及任何兼容 MCP 的智能体构建。

litopys-dev.github.io/litopys — 安装、截图和快速入门

🇺🇦 Читати українською

为什么选择 Litopys？

目前的 AI 智能体内存系统往往需要在以下两者间做出权衡：要么是沉重的向量数据库（伴随子进程泄漏和约 500 MB 的内存占用），要么是无法扩展到几十条笔记以上的纯 Markdown 文件。

Litopys 选择了第三条道路： 一个以纯 Markdown 存储的类型化知识图谱，通过轻量级 MCP 层（约 75 MB 内存）提供服务，既可手动编辑，又能通过关键词和结构进行查询。Litopys 在乌克兰语中意为“编年史”——因为这正是你 AI 内存应有的样子：一份关于它了解你的内容、时间及原因的动态记录。

Related MCP server: auxly-memory-cli

特性

• 🧠 类型化图谱 — 6 种节点类型（人物、项目、系统、概念、事件、课程）和 11 种一等关系

• 🔌 原生 MCP — 适用于 Claude Code、Claude Desktop、Cursor、Cline 或任何 MCP 客户端（参见 docs/integrations）

• 📝 Markdown 优先 — 每个节点都是带有 YAML frontmatter 的纯 .md 文件。可手动编辑、可 grep 搜索、支持 git 版本控制

• 🤖 模型无关提取器 — 支持 Anthropic、OpenAI 或本地 Ollama。根据你的资源/成本预算进行选择（参见下方的 资源占用）。事实经过隔离区处理，确保未经审核的内容不会进入库中

• 🌐 Web 仪表盘 — 在 http://localhost:3999 浏览、搜索、编辑、可视化图谱并审查隔离区

• 🔐 保持本地化 — 图谱以文件形式存储在 ~/.litopys/graph/ 中；服务器默认绑定到 127.0.0.1；无遥测数据

仪表盘

截图基于 docs/screenshots/ 中捆绑的合成演示图谱，而非作者的个人笔记。

状态

v0.1.2 已发布 — 提供 Linux / macOS / Windows (x64 + arm64) 的预构建二进制文件，并附带由 install.sh 验证的 SHA-256 校验和。这是在 v0.1.1 稳定版基础上的安全更新 — 参见 CHANGELOG。公共接口（MCP 工具、CLI、JSON 导出 schemaVersion: 1、磁盘 Markdown 布局）已冻结；破坏性变更将作为 0.2.x 发布。

核心图谱、MCP 服务器（5 个工具，stdio + HTTP/SSE）、提取器 + 隔离区 + 每周摘要、定时守护进程、仪表盘（读 + 写 + 图谱可视化 + 隔离区审查）、身份解析防护、单二进制构建、一行安装命令、各客户端集成文档 — 全部已发布。参见 后续计划 了解规划中的更新。

资源占用

来自作者本人安装环境（Ubuntu, Bun 1.x）的真实数据。MCP 服务器开销很小；提取器是主要的成本来源，具体取决于你选择的适配器。

因此，最低常驻成本约为 75 MB（MCP 服务器）。提取是可选的 — 你可以仅在智能体中以读/写模式运行 Litopys，而无需启动守护进程。如果你启用了提取功能，本地 Ollama 方案是用内存换取金钱；Anthropic/OpenAI 方案是用金钱换取内存。Ollama 的 keep_alive 意味着 3B/7B 的内存占用是暂时的 — 模型会在任务完成后几分钟内从内存中释放。

快速入门

一行安装命令（Linux / macOS）：

curl -fsSL https://raw.githubusercontent.com/litopys-dev/litopys/main/install.sh | sh

这将下载一个约 100 MB 的二进制文件到 ~/.local/bin/litopys，使用所需的子目录初始化 ~/.litopys/graph/，并打印 MCP 注册提示。

通过在 管道符后 放置赋值来指定特定版本 — 在 curl 之前设置的环境变量仅作用于 curl 本身，而非管道后的 shell：

curl -fsSL https://raw.githubusercontent.com/litopys-dev/litopys/main/install.sh | LITOPYS_VERSION=v0.1.2 sh

然后向你的客户端注册 MCP 服务器：

# Claude Code
claude mcp add litopys -- ~/.local/bin/litopys mcp stdio

// Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "litopys": {
      "command": "/home/you/.local/bin/litopys",
      "args": ["mcp", "stdio"]
    }
  }
}

重启客户端。litopys://startup-context 资源会在每次新会话时自动加载所有者资料、活跃项目、近期事件和关键课程。智能体通过五个 MCP 工具进行读写：litopys_search、litopys_get、litopys_related、litopys_create、litopys_link。

完整的客户端特定配置指南位于 docs/integrations/ — 涵盖 Claude Code、Claude Desktop、Cursor、Cline、ChatGPT Connectors、Gemini。

远程 (HTTP/SSE) 模式

适用于远程客户端（Claude Desktop 连接器、基于浏览器的 MCP 主机）：

LITOPYS_MCP_TOKEN=your-secret litopys mcp http
# listens on 127.0.0.1:7777 by default
# set LITOPYS_MCP_BIND_ADDR=0.0.0.0 + TLS proxy for remote exposure
# set LITOPYS_MCP_CORS_ORIGIN=https://your-client to enable CORS

开发安装（从源码）

git clone https://github.com/litopys-dev/litopys.git
cd litopys
bun install
bun run build:binary       # produces dist/litopys

可选 — 用于长期运行转录的守护进程

cp packages/daemon/systemd/litopys-daemon.{service,timer} ~/.config/systemd/user/
systemctl --user enable --now litopys-daemon.timer

可选 — Web 仪表盘自动启动

仪表盘（litopys viewer）可以作为 systemd 用户服务运行，以便在每次重启后自动恢复。

litopys viewer install        # generates token, writes unit, enables service
litopys viewer install --lan  # same + binds to 0.0.0.0 for LAN access
systemctl --user status litopys-viewer

# Remove:
litopys viewer uninstall

访问令牌。 viewer install 会自动生成一个随机令牌并将其保存到 ~/.litopys/viewer.token。安装输出会打印一个嵌入了令牌的即用型 URL：

✓ litopys-viewer installed

  Open dashboard:    http://localhost:3999/?token=<token>
  Share with others: http://192.168.1.x:3999/?token=<token>   # --lan only

  Opening the link once saves the token — no re-entry needed.
  Retrieve token later: cat ~/.litopys/viewer.token

打开该 URL 一次即可将令牌保存到 localStorage — 无需后续提示。若要与他人共享写权限，请发送包含 ?token=… 的 URL。若要随时检索令牌，请运行 cat ~/.litopys/viewer.token。

GET 端点（浏览、搜索、图谱视图）始终开放。修改端点（创建/编辑/删除节点、接受或拒绝隔离区内容）需要令牌。

或者在运行 install.sh 时设置 LITOPYS_ENABLE_VIEWER=1 以将其作为一行安装的一部分启用。如果你希望仪表盘在注销后保持运行，需要执行 loginctl enable-linger $USER。

完整性检查

litopys check           # human-readable report, grouped by error kind
litopys check --json    # { nodeCount, edgeCount, errorCount, errors[] } for CI

加载并解析整个图谱，然后标记损坏的引用、重复的 ID、类型错误的关系以及解析/验证失败。当发现问题时返回非零退出码 — 将其放入 git pre-push 钩子或 CI 步骤中，确保偏差不会悄无声息地进入库中。

备份你的图谱

Litopys 将所有内容作为纯 Markdown 存储在 ~/.litopys/graph/ 中，因此任何文件版本控制工具都适用。两种常见方法：

Git + 私有远程仓库（增量历史、异地备份、免费）：

cd ~/.litopys
git init
git add graph/ .gitignore README.md
git commit -m "baseline"
gh repo create my-litopys-graph --private --source=. --push

此后，每次会话结束钩子或手动接受操作都会使工作区变脏 — 定期执行 git add -A && git commit -m "sync" && git push 以保持备份最新。你的图谱包含个人事实，因此请务必保持远程仓库为 私有。

JSON 快照（便携、可对比、工具友好）：

litopys export > graph.json              # compact
litopys export --pretty > graph.json     # indented, VCS-friendly
litopys export --no-body > meta.json     # metadata only, strip markdown bodies

转储文件包含 meta（导出时间、计数、schemaVersion）以及按 ID 排序的所有节点和按 (from, relation, to) 排序的边 — 跨运行具有确定性，因此 diff graph-yesterday.json graph-today.json 可以准确告诉你 LLM/守护进程添加了什么。将其输入分析工具、在主机间迁移或与代码一起提交。

从新主机（或重装后）的快照恢复：

litopys import graph.json --dry-run   # preview the plan
litopys import graph.json             # create new nodes, skip existing ones
litopys import graph.json --force     # also overwrite existing ids

默认行为是保守的 — 除非传入 --force，否则不会触碰现有节点。每个节点在写入前都会根据 schema 进行验证，因此损坏的快照会在任何内容写入磁盘前中止。

发布历史

参见 CHANGELOG.md。未来的工作将由真实用户反馈驱动 — 如果有任何问题，请提交 issue。

设计原则

• 智能体无关。 不对任何 LLM 供应商或客户端有硬依赖。MCP 是唯一的集成点。Ollama 是默认提取器；Anthropic/OpenAI 是可选适配器。

• 数据便携。 图谱在磁盘上是纯 Markdown + YAML frontmatter。在任何编辑器中可读，在 git 中可版本化，在 shell 中可 grep。

• 轻量级运行时。 MCP 服务器内存占用约 75 MB。提取器是进程外的，按你的计划运行，而不是在每次请求时运行 — 参见 资源占用 获取各适配器的完整成本明细。

• 可选集成。 客户端特定的辅助工具（钩子、配置片段）位于 docs/integrations/ — 你可以在不使用任何这些工具的情况下使用 Litopys。

许可证

MIT © 2026 Denis Blashchytsia 及 Litopys 贡献者。