locus

Locus

专为自主 AI Agent 打造的层级式 Markdown 记忆系统。每个目录都是宫殿中的一间房（locus），其中包含可按需查阅的特定知识。 名称取自 记忆宫殿法 中的基本单元。

核心理念： 保持上下文窗口精简。只加载所需的房间，而非整座宫殿。

---

工作原理

palace/
  INDEX.md                    ← always read first (~50 lines max)
  global/
    toolchain/
      toolchain.md            ← canonical facts about tools
  projects/
    my-project/
      my-project.md           ← room overview + key files
      technical-gotchas.md    ← specialty: issues & resolutions
      sessions/
        2026-03-02.md         ← append-only session log

Agent 读取 INDEX.md，导航至相关房间，并只读取该房间。 会话日志不断累积，直到通过整合将其合并到规范文件中。

完整文档请参阅 wiki。

---

快速开始

# Install
pip install locus-mcp
# or: uvx locus-mcp --palace ~/.locus  (no install needed)

# Create a palace from the packaged example
locus init ~/.locus
# Edit ~/.locus/INDEX.md to describe your palace

# Run the MCP server
locus-mcp --palace ~/.locus
# or: LOCUS_PALACE=~/.locus locus-mcp

---

安装

MCP 服务（推荐用于支持 MCP 的客户端）

pip install locus-mcp

也可以使用 uvx 运行，无需安装：

uvx locus-mcp --palace ~/.locus

Agent 技能

技能文件是 Locus 中唯一针对特定运行环境编写的部分。宫殿约定、MCP 服务以及 recall / lint / index CLI 均与运行环境无关，可用于任何能够读取文件或通过 MCP 通信的环境。skills/claude/ 中的技能专为 Claude Code 编写和维护，也是此处唯一提供的一套技能。这些技能是带有 YAML frontmatter 的纯 Markdown 文件，其他运行环境也可以自行改编。过去，针对不同运行环境的副本位于 skills/codex/ 和 skills/gemini/；后来将其移除，因为维护三个版本的成本超过了收益。

从克隆的仓库中安装：

git clone https://github.com/Nano-Nimbus/locus.git
cd locus
make install-skills            # copies skills/claude/* to ~/.claude/skills/
make install-skills-dry        # print what would be copied, write nothing

CLAUDE_SKILLS_DIR 可覆盖目标目录。

技能	命令	描述
locus	/locus	回忆信息、导航宫殿、编写房间和会话日志、重新生成索引
locus-consolidate	/locus-consolidate	将会话日志合并到规范文件中
locus-audit	/locus-audit	审查宫殿的健康状况
locus-feedback	/locus-feedback	记录对宫殿信息回忆的明确反馈
locus-release	/locus-release	发布后验证工作流（贡献者使用）
locus-security	/locus-security	信任标签、nonce 规范以及 locus-security CLI
locus-palace-init	/locus-palace-init	从现有记忆文件初始化宫殿

Agent SDK（Python）

pip install locus-mcp
locus --palace ~/.locus --task "What toolchain conventions are set?"

---

MCP 服务

locus-mcp 命令通过 Model Context Protocol 提供五种工具。

所有本地集成都请使用 stdio（Claude Desktop、Claude Code、Codex、Gemini——默认设置，无需额外标志）。 SSE 传输可用于网络部署（--transport sse），并且需要显式设置 FASTMCP_HOST=0.0.0.0——服务默认绑定到 loopback。

工具	描述
memory_list	返回 INDEX.md（无参数时）或列出某个房间的文件
memory_read	读取宫殿中的任意文件
memory_write	原子方式写入文件（受保护——无法写入 _metrics/、sessions/、.sig/、.security/）
memory_search	在共享的 FTS5 索引中进行排序全文搜索（见回忆）；没有 FTS5 时仅使用 ripgrep
memory_batch	单次调用最多读取 20 个宫殿文件——适用于加载多个房间

添加 --security 可在读取时启用 Ed25519 签名验证，并在写入时自动签名。 详见下文的安全性。

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "locus": {
      "command": "locus-mcp",
      "args": ["--palace", "/path/to/palace"]
    }
  }
}

也可以使用 uvx（无需安装）：

{
  "mcpServers": {
    "locus": {
      "command": "uvx",
      "args": ["locus-mcp", "--palace", "/path/to/palace"]
    }
  }
}

Cursor / Zed

{
  "mcp": {
    "servers": {
      "locus": {
        "command": "locus-mcp",
        "args": ["--palace", "/path/to/palace"]
      }
    }
  }
}

环境变量

所有客户端都支持使用 LOCUS_PALACE 替代 --palace：

export LOCUS_PALACE=~/.locus
locus-mcp

完整的客户端设置指南请参阅 MCP Server Configuration，架构详情请参阅 spec/mcp-server.md。

---

Recall

locus recall 只需一次调用即可回答“我已经知道关于这件事的什么？”，速度足够快，可以通过钩子对每条提示词运行。它会在任意数量的 Markdown 根目录上维护 SQLite FTS5 索引（仅使用标准库，无需 PyYAML）：可以是 palace、OKF 包、Claude Code 记忆目录，也可以同时包含所有这些目录。

locus recall --root ~/memory --root ./docs "why does the flux kustomization stall"

Recalled memory:
1. Flux healthcheck stall (human-reviewed, 2026-08-22)
   /home/me/memory/project_flux-healthcheck-stall.md
   Flux Kustomization with wait:true stalls on health checks for a bad revision ...
2. [STALE] Old Flux bootstrap procedure (unverified, 2025-11-02)
   /home/me/docs/runbooks/flux-bootstrap.md
   Bootstrap Flux with a personal access token ...

标志	默认值	含义
--root DIR	.locus.toml，然后是 LOCUS_PALACE	要编入索引的目录；可重复指定
-k N	3	命中数
--budget BYTES	4096	文本输出的硬性上限
--include journal	关闭	包含 type: Journal 文件
--type TYPE	全部	仅包含此 frontmatter 类型；可重复指定
--json	关闭	输出 JSON 列表，而不是文本
--refresh	关闭	从头重建索引

结果由 frontmatter 决定：title（或 name，或第一个标题）、description、tags、type（或 metadata.type）、modified（否则使用 generated.at，再否则使用文件 mtime）、status、stale_after 和 verified。排名使用 bm25，标题和描述的权重高于正文；完全并列时，优先选择人工审核的文件，其次选择 modified 时间最新的文件。如果某条结果的 stale_after 已过期或其 status 为 deprecated，则会标记为 STALE。信任层级遵循 OKF：unverified、machine-confirmed（仅限非人工的 verified 条目）、human-reviewed（任何 by 以 human: 开头的 verified 条目）。

根目录可以在项目目录或任意父目录的 .locus.toml 中配置：

[recall]
roots = ["docs", "~/memory/shared"]

索引存储在 ${XDG_CACHE_HOME:-~/.cache}/locus/<hash-of-roots>.sqlite，不会存放在任何根目录内，并且每次调用时都会增量刷新（先比较 mtime，再比较内容哈希）。没有命中时，文本输出为空，退出状态仍为 0，因此可以无条件调用它作为提示词钩子：

#!/bin/sh
# Claude Code UserPromptSubmit hook: whatever this prints is injected as context.
prompt=$(jq -r .prompt)
exec locus recall -k 3 --budget 4096 "$prompt"

MCP 服务的 memory_search 使用相同的索引，因此 MCP 结果的排名方式也相同。完整规则请参阅 spec/recall.md。

---

Lint 和索引

locus lint 会检查 Markdown 根目录是否符合 Open Knowledge Format v0.2 规范及 Locus palace 约定。locus index 会生成这些约定所定义的索引文件。两者都会读取相同的 frontmatter recall 索引，并且都不会导入 Agent SDK，因此只检查规范符合性的 CI 任务无需安装它。

locus lint  --root docs --check          # CI gate: exit 1 on any error
locus lint  --root docs --fix            # add inferable fields, rewrite nothing
locus index --root docs --check          # exit 1 when a generated index drifted

docs/runbooks/valve-chatter.md: error [okf.type-missing] frontmatter has no non-empty type (fix: add type: Runbook)
docs/log.md: error [okf.log-order] entries run oldest first: 2026-05-09 follows 2026-05-01
docs/reference/platform.md: warning [locus.size-limit] 214 lines exceeds the 200-line soft limit for a specialty file
2 error(s), 1 warning(s), 1 fixable

lint

标志	默认值	含义
--root DIR	.locus.toml，然后是 LOCUS_PALACE	要检查的目录；可重复指定
--check	关闭	发生任何错误时以非零状态退出。适用于 CI
--strict	关闭	在 --check 下将警告视为错误
--fix	关闭	添加可推断的字段。绝不重写现有键
--type-map DIR=TYPE	无	为 DIR 下的内容推断此 OKF 类型；可重复指定
--archive-glob GLOB	无	应带有 status: deprecated 的路径；可重复指定
--json	关闭	输出 JSON 报告，而非文本

规则分为两类。okf.* 检查规范要求的内容：每个非保留文档都必须有可解析的 frontmatter 块和非空的 type，index.md 除了包根目录中的 okf_version 外不得包含其他 frontmatter，log.md 必须以日期为标题并按时间倒序排列，时间戳必须符合 ISO 8601。未知键和未知类型值绝不会被报告：规范要求使用方能够容忍这两种情况。locus.* 检查宫殿约定：spec/size-limits.md 中的大小限制，以及 spec/room-conventions.md 中的房间主文件规则。

错误会导致 --check 失败；警告仅供参考。宫殿完全不带 frontmatter 也是合理的，因此在宫殿根目录下，缺少类型规则会作为警告，而不会因宫殿规范本身描述的布局导致 CI 失败。

--fix 只会添加三个字段：来自 --type-map 或 [lint.types] 的 type，来自文件首次 git 提交时间的 generated.at，以及用于归档路径的 status: deprecated。它绝不会重写或删除键，也绝不会凭空创建 generated 块（文件中没有信息说明是谁生成了它），重复运行两次会产生完全相同的字节内容。

index

标志	默认值	含义
--root DIR	.locus.toml，然后是 LOCUS_PALACE	要编制索引的目录；可重复指定
--check	关闭	不写入任何内容；发现差异时以非零状态退出。适用于 CI
--kind	auto	强制将内容分类为 okf、palace 或 memory
--json	关闭	输出 JSON 报告，而非文本

生成的内容取决于根目录：OKF 包会按照第 8 节的格式为每个目录生成一个 index.md（每行格式为 * [Title](path) - description，且只有包根目录带有 okf_version: "0.2" frontmatter）；宫殿会生成包含 50 行的路由表 INDEX.md；Claude Code 记忆目录会生成 MEMORY.md，其中每个主题文件对应一行 - [Title](file.md) - description。输出具有确定性，因此 --check 会进行字节比较，而且只会写入索引文件。

通过一个 .locus.toml 同时配置两者：

[lint]
roots = ["docs"]
archive_globs = ["archive/*"]

[lint.types]
"." = "Reference"
runbooks = "Runbook"

完整规则见 spec/lint-and-index.md。

---

安全性

安全系统（--security）会为宫殿中的每个文件添加 Ed25519 签名，并为每个 Agent 会话生成唯一的加密随机数。工具输出会在 Agent 查看前标记为 [TRUSTED]、[DATA] 或 [CRITICAL-DATA]。Agent 技能（locus-security）会教会 Agent 从 [DATA] 内容中提取事实，但绝不遵循其中的指令。

# One-time setup
locus-security init-config --palace ~/.locus   # writes locus-security.yaml
locus-security init-keys   --palace ~/.locus
locus-security sign-all    --palace ~/.locus

# Run with security enabled
locus-mcp --palace ~/.locus --security
locus --palace ~/.locus --security --task "..."

locus-security CLI 有五个子命令：init-config（从包内附带的副本写入带注释的 locus-security.yaml）、init-keys、sign-all、verify-all（若任何文件验证失败，或宫殿中没有可签名文件，则以状态码 1 退出），以及 rotate-keys。sign-all 会列出无法读取为 UTF-8 的文件并跳过，而不是中止运行；如果跳过了任何文件，则以状态码 1 退出。两个命令都不会跟随目标解析到宫殿目录之外的符号链接：sign-all 会列出并跳过这些链接，verify-all 则会将其报告为失败。

**威胁模型：**直接提示注入、记忆投毒、通过外部数据进行间接注入、随机数外泄、多轮上下文漂移。

完整协议、配置参考和设计决策见 docs/security.md。

---

基准测试

对于特定查询，宫殿式导航加载的上下文行数比扁平记忆少 52%，同时保持完整召回。仅限会话的查询（尚未整合的近期工作）只能通过宫殿访问。

Palace: 822 lines / 9 queries found   avg  91 lines/query · 3.2 calls
Flat:  1719 lines / 8 queries found   avg 191 lines/query · 2.0 calls

图表和完整方法说明请参阅 docs/benchmarks.md。

---

结构

example-palace/   Palace template; `locus init` writes it into a new palace
spec/             Palace convention definitions:
  index-format.md       INDEX.md rules and routing
  room-conventions.md   Room structure and naming
  size-limits.md        Context budget thresholds
  write-modes.md        Session logs vs canonical edits
  mcp-server.md         MCP server architecture and safety model
  recall.md             locus recall: roots, index, ranking, trust tier, STALE
  lint-and-index.md     locus lint and locus index: OKF conformance, generated indexes
  metrics-schema.md     Run metrics JSON schema
  audit-algorithm.md    Palace health scoring
  health-report-format.md  Audit report structure
  inferred-feedback.md  Disagreement signal classification
templates/        Templates for INDEX.md, rooms, session logs, locus-security.yaml
                  (`locus init --show list`; both trees ship inside the wheel)
skills/
  claude/         SKILL.md files for Claude Code + Agent SDK (the only maintained set)
    locus/              Recall, palace navigation, writes, index and lint
    locus-consolidate/  Room consolidation
    locus-audit/        Palace health audit
    locus-feedback/     Recall quality feedback
    locus-palace-init/  Bootstrap a palace from existing memory files
    locus-release/      Post-release verification (contributors)
    locus-security/     Security conventions (trust tags, nonce discipline)
docs/
  architecture.md       Mermaid diagrams — palace, MCP, security, agent interfaces
  benchmarks.md         Benchmark results and charts (palace vs flat, security overhead)
  onboarding.md         Step-by-step agent onboarding guide
  security.md           Full security protocol, key management, config reference
  bench/                Per-version benchmark JSON (read by generate-charts.py)
scripts/
  bench-mcp.py          45-case MCP integration benchmark (includes security + batch)
  bench-compare.py      Palace vs flat recall comparison
  generate-charts.py    Regenerate docs/img/ charts (reads docs/bench/ automatically)
locus/
  agent/          Python Agent SDK (CLI + metrics)
  audit/          Palace health auditor (locus-audit CLI)
  feedback/       Inferred feedback classifier
  mcp/            MCP server (locus-mcp CLI) — palace.py, server.py, main.py
  conform/        locus lint and locus index: OKF conformance, index generation
  recall/         locus recall: FTS5 index shared with memory_search
  security/       Ed25519 security system — keys, signing, taint, nonce, middleware
  scaffold.py     locus init: packaged templates and palace scaffolding
  utils.py        Shared utilities (slug_from_path)

---

路线图

里程碑	状态	重点
v0.1 - 基础	✅ 已完成	规范、约定、大小限制
v0.2 - 核心宫殿	✅ 已完成	模板、技能、Agent SDK、基准测试
v0.3 - 性能指标	✅ 已完成	上下文跟踪、反馈、建议
v0.4 - 自我评估	✅ 已完成	宫殿审计、健康报告、推断反馈
v0.5 - MCP 服务	✅ 已完成	支持 memory_list/read/write/search 的 MCP 服务
v0.6 - 公开发布	✅ 已完成	基准测试、文档、CI、PyPI
v0.7 - 远程 MCP 服务	✅ 已完成	SSE 传输、Bearer 身份验证、Docker 镜像、K8s 部署
v0.8 - 自动记忆桥接	✅ 已完成	Claude Code 自动记忆检测、memory_batch 工具
v0.9 - 安全系统	✅ 已完成	Ed25519 签名、污点跟踪、nonce 水印、--security 标志

---

参与贡献

开发环境设置、测试说明和 PR 指南请参阅 CONTRIBUTING.md。

许可证

MIT