Droste

---

快速入门

从 PyPI 或 GitHub Releases 安装 v1.3.0。 请参阅发布状态。

# Windows
python -m pip install --upgrade droste-memory

# macOS / Linux
python3 -m pip install --upgrade droste-memory

droste index . # index the current repo
droste view    # open the fractal galaxy in your browser

安装一次，然后建立索引并查看。droste view 会打开代码的全屏可缩放地图 ——滚动即可从项目星体深入文件夹轨道，再到 各个函数及其已索引的关系。

想让 Agent 使用，而不是自己查看？

droste explore "checkout flow" --tokens 1500

将返回的节点 ID 用作 --focus，并选择 --level map、structure 或 source，以不同细节级别浏览同一片区域。used 会根据所选 tokenizer 测量完整的精简响应。源码正文无法容纳时会明确降级。运行一次 droste explore --prepare-tokenizers，即可准备小型 token 词表，供之后离线使用。请参阅 工作流、回执和测量得出的限制。 较早的 droste context --budget 界面仍按字符数控制预算。

日常代码调查：

droste check                         # verify source hashes and index coverage
droste find calculate                # find symbol IDs, paths and line numbers
droste references calculate --direction both
droste references helper --file src/math.py --direction callers --depth 3
droste watch .                       # refresh after additions, edits, renames or deletions

references 会为含义不明确的名称返回候选项；请选择文件或符号 ID， 不要靠猜。Python 链接会包含调用表达式和源码行。 其他语言链接会报告其启发式解析方法。对于过时、不完整或无法验证的索引， check 会以状态码 1 退出。上下文响应会通过快速检查文件大小和修改时间来警告 索引覆盖范围是否过时或不完整；check 还会验证 SHA-256 哈希值。依赖旧索引前，请先运行它。

索引会遵循嵌套的 .gitignore 规则和项目根目录下的 .drosteignore （Git 忽略语法；最后应用）。符号链接、生成的打包文件、依赖目录以及 Droste 自身的存储均会排除。 使用 --db 为每个项目指定独立数据库，以便运行互不干扰的写入进程。watch 会批量刷新根目录，并 重用未更改的提取结果和嵌入；view 仍然是快照，因此要查看刷新后的图，请重新打开它。

不带参数运行 droste 会显示命令面板：

                  .-----------------------.
             .----'           |           '----.
         .---'          .-----+-----.          '---.
       .'          .----'     |     '----.          '.
      /        .---'      .---+---.      '---.        \
     /      .-'        .-'    |    '-.        '-.      \
    |     .'        .-'   .---+---.   '-.        '.     |
    |    /        .'    .'    |    '.    '.        \    |
    |   |        |     |   .--+--.   |     |        |   |
    | --+--------+-----+---+  @  +---+-----+--------+-- |
    |   |        |     |   '--+--'   |     |        |   |
    |    \        '.    '.    |    .'    .'        /    |
    |     '.        '-.   '---+---'   .-'        .'     |
     \      '-.        '-.    |    .-'        .-'      /
      \        '---.      '---+---'      .---'        /
       '.          '----.     |     .----'          .'
         '---.          '-----+-----'          .---'
             '----.           |           .----'
                  '-----------------------'

DROSTE-MEMORY // RIGID FRACTAL RADIAL LAYOUT
Local Graph Engine v1.3.0-Alpha-Sharded

Commands
  droste index <path> [--reset]
  droste status
  droste zoom <symbol_name>
  droste context [query] --budget 1500
  droste explore [query] --tokens 2000 --level map|structure|source
  droste mcp

Fast path: droste context hub_core --budget 1000 | clip

---

有何不同

Droste 将词法和语义检索与静态代码图及交互式地图相结合。即使调用方和被调用方与查询共享的词语很少，图也能将它们纳入上下文。其他工具也提供基于图的 MCP 检索；请参阅注明日期的生态系统评估。

Droste 专注于精简的 Python CLI、预算受限的上下文和可视化探索。该图是静态近似：名称匹配和跨语言桥接可能产生误报，且不能证明运行时行为。

实用的构建模块包括：

• 可解释的静态引用。 Python 调用会使用词法作用域、导入别名和显式的 self/cls 成员。动态接收者仍无法解析。其他语言使用局部匹配／唯一名称匹配；有歧义的候选项会被跳过。
• 跨语言桥接。 Droste 会跨语言建立链接——应用代码可连接到 SQL 函数／表（.rpc('x')、.from('table')）、边缘函数，以及任意两种语言中同名的处理程序。你的 Dart/TS/Python 前端和数据库不再是地图上相互分离的两个世界。
• 可视化探索。 在交互式放射状地图中浏览文件、符号和已索引的关系。
• 零配置、本地运行。 无需云服务、账号或 API 密钥。fastembed（ONNX，无需 torch）可提供真正的语义能力；确定性回退方案则确保它能在任何地方运行。

多语言：Python（AST）+ tree-sitter，支持 Dart、TypeScript/JavaScript、Go、Rust、Java、C#、C/C++、Kotlin、Swift、Ruby、PHP、SQL——包括符号和边。

诚实说明适用范围： 经测量的优势在于结构／因果检索。在纯语义“概念”查询上，它与向量基线相比具有竞争力，但并非显著领先。跨语言桥接在目标确实定义于已索引仓库中的场景下效果最佳（例如迁移文件中的 SQL 架构）。

---

基准测试

公开源代码验证使用固定版本的 Requests 和 CPython，并对边断言进行人工标注。目前通过了 20 项断言中的 19 项：找到了 16 条预期边中的 15 条，且未生成 4 条禁止边。漏掉的边已有记录；这个小型语料库并非 Agent 任务基准，也不是与竞品的对比。

python eval/public_corpus.py --output public-results.json

评估脚本会将结构检索与词法和向量基线进行比较，并使用从相同代码中提取的调用方／被调用方关系作为参照。这衡量的是图邻居检索，而非 Agent 任务完成情况，也不代表优于其他产品。在发布固定的公开语料库、固定版本和完整结果文件之前，先前的醒目数据将不再列出。

python eval/comparative_eval.py --repos /path/to/public/repo --sample 60 --seed 7 --json results.json

进行语义对比时，请使用真实的嵌入后端；离线哈希模式具有确定性，但无法提供语义相似度。

---

工作原理

• 静态图。 Python 作用域和导入会解析具名调用；对于其他受支持的语言，tree-sitter 会提供定义和引用。基于名称的链接以及跨语言的数据库／字符串桥接均为启发式结果，并会在引用结果中标注。这并不意味着会解析运行时行为或完整类型。
• 混合种子。 查询会通过词法得分与语义余弦相似度的归一化组合进行匹配（fastembed bge-small-en-v1.5，384 维），然后图会从种子开始双向扩展（被调用方和调用方）。
• 渐进式探索器。 explore 会按参考分词器的 token 数量为完整响应设置预算，包括元数据。按节点 ID 浏览映射、结构和源代码；确认精确保留的视图，以免重新发送其正文。
• 旧版上下文打包器。 context --budget 的单位是字符，最低值为 500。完整源代码、契约或显式源代码存根都会计入此有效上限，包括分隔符。此旧版接口不保证针对特定分词器的计数。
• 分片持久化。 每个文件在数据库专属的 .droste/ 目录中对应一个分片；通过 blake2b 跟踪变更，重新索引时只重写发生变化的内容；以原子方式替换文件，并最后写入元数据。多文件更新不是事务；每个数据库只使用一个写入方，并在写入中断后重新索引。

---

将其用作 MCP 服务

Droste 是一个可直接替换使用的 MCP 服务——AI Agent 可以将其用作主要代码记忆，而不是盲目读取文件。将以下内容添加到客户端配置文件中（例如 Cursor、Claude Desktop 或 Codex）：

首先安装或升级到当前 PyPI 版本：

# Windows
python -m pip install --upgrade droste-memory

# macOS / Linux
python3 -m pip install --upgrade droste-memory

droste mcp --help

对于 Codex，在 Windows 上将以下内容添加到 C:\Users\<you>\.codex\config.toml，或在 macOS/Linux 上添加到 ~/.codex/config.toml：

[mcp_servers.droste]
command = "droste"
args = ["mcp"]
startup_timeout_sec = 120

已安装的软件包会将默认数据库存储在 Windows 的 %LOCALAPPDATA%/Droste、macOS 的 ~/Library/Application Support/Droste，或 Linux 的 ${XDG_DATA_HOME:-~/.local/share}/droste 中。从源代码检出的版本会保留其仓库本地数据库。设置 DROSTE_DB 或传入 --db 可覆盖此设置。旧版安装中的现有数据库不会自动迁移；将 --db 指向旧文件以继续使用，或重新索引源代码。

如需明确启用离线运行，请设置 DROSTE_EMBEDDING_BACKEND=hash。 默认的 auto 后端可能会在首次使用时下载嵌入模型；代码会在本地处理。Hash 模式以语义检索能力换取确定性且无需网络的嵌入。droste view 提供快照；索引后请重新运行。

默认情况下，droste mcp 使用 Droste 的全局本地数据库。这适用于快速使用和小型工作流。对于正式的多仓库工作，请为每个仓库使用一个数据库，以便每个项目的记忆彼此隔离，Agent 也可以安全地使用 reset=true 重新索引该项目。

--db 选项是全局选项，因此请将它放在 mcp 之前：

# Windows example
[mcp_servers.droste]
command = "droste"
args = ["--db", "C:/Users/you/AppData/Local/Droste/my-project/droste_memory_db.json", "mcp"]
startup_timeout_sec = 120

# macOS / Linux example
[mcp_servers.droste]
command = "droste"
args = ["--db", "/Users/you/.local/share/droste/my-project/droste_memory_db.json", "mcp"]
startup_timeout_sec = 120

对于基于 JSON 的 MCP 客户端：

{
  "mcpServers": {
    "droste": {
      "command": "droste",
      "args": ["mcp"]
    }
  }
}

基于 JSON 的客户端也可以使用相同的数据库隔离模式：

{
  "mcpServers": {
    "droste": {
      "command": "droste",
      "args": [
        "--db",
        "/absolute/path/to/droste_memory_db.json",
        "mcp"
      ]
    }
  }
}

更改 MCP 配置后，请重启客户端。为项目建立索引，调用 droste_check_index，然后在获取上下文前使用符号查找和引用功能。进行更改前，请检查实际源代码。

主要工具：droste_index_project、droste_check_index、 droste_find_symbols、droste_references、droste_explore、droste_get_context、droste_status。 辅助画布工具：inject_concept、move_camera_and_zoom、get_space_status。 droste_explore 是渐进式 token 预算路径。现有已打开的 MCP 连接会继续使用较早的进程，直到重新连接；新连接会加载升级后的工具列表。保留视图句柄仅在客户端仍保留对应文本时有效；压缩后请清除这些句柄。

---

将其用作 Agent 技能

Droste 还提供适用于 Codex 和 Claude 的 Agent 技能模板。它们会教 Agent 如何安全地使用 Droste：隔离数据库、建立索引、使用 droste context、配置 MCP，以及设置防止根目录污染的保护措施。

Codex 技能：

integrations/codex-skill/droste-code-memory/

兼容 Claude 的技能：

integrations/claude-skill/droste-code-memory/

将文件夹复制到 Codex 技能目录即可安装 Codex 技能：

# macOS / Linux
mkdir -p ~/.codex/skills
cp -R integrations/codex-skill/droste-code-memory ~/.codex/skills/

# Windows PowerShell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\skills" | Out-Null
Copy-Item -Recurse -Force integrations\codex-skill\droste-code-memory "$env:USERPROFILE\.codex\skills\"

然后向 Codex 提出：

Use $droste-code-memory to index this repository and retrieve causal context before editing.

对于 Claude，请将 Claude 技能文件夹导入或复制为 Claude Skill 软件包，并将其中的 SKILL.md、references/ 和 scripts/ 保存在一起。

---

开发

pip install -e ".[dev]"
pytest                            # deterministic regression suite (tests/)
python eval/comparative_eval.py   # retrieval benchmark vs lexical & vector cores

tests/ = 不变量与并发测试（往返、脏数据判定器、打包器保护措施、跨进程分片竞争）。eval/ = 性能／质量基准测试。

---

状态

v1.3.0（alpha）。 渐进式令牌预算探索、经过测试的 CLI／MCP 工作流、源文件新鲜度检查，以及明确受限的静态图。动态分派、接收者类型推断和完整的跨语言解析仍不在当前保证范围内。每个数据库只使用一个写入方。请参阅验证与限制。

v1.3.0 新增内容

• 使用 droste explore 和 droste_explore，按 map → structure → source 搜索并逐层查看。
• 使用真实的 o200k_base／cl100k_base 令牌计数限制完整响应。
• 仅当客户端确认仍保留原视图时，才复用完全未变的视图。
• 导航前验证源文件哈希，并显示降级后的详细信息和省略内容。
• 添加录制的交互式演示、精确的公开响应，以及针对第十个 MCP 工具的已安装 wheel 检查。

v1.2.1 新增内容

• 优先处理明确且唯一的符号查询，而非语义相似项。
• 在紧凑上下文中保留完整的源文件位置。
• 发布实用 Requests 调查，其中包括尚未解决的发现和追踪弱点；不作对比性能声明。

v1.2.0 新增内容

• 修复 Python 作用域／导入解析，并停止猜测有歧义的名称匹配。
• 添加 find、references、check 及对应的 MCP 工具，并提供源文件证据。
• 在编辑、添加、删除和重命名后刷新所有受支持的语言。
• 报告覆盖不完整和上下文过时；使用 --reset 时保留其他根目录。
• 遵循忽略规则，并实际收集 Java、C#、Ruby 和 PHP 文件。
• 按模型标识分隔缓存的嵌入，并在切换后端时重建。
• 添加独立的公开源代码断言，并测试全部九个 MCP 工具。

v1.1.7 新增内容

• 要求使用兼容的 1.x SDK，恢复全新安装后的 MCP 启动。
• 使用当前的 tree-sitter Python API，恢复多语言语法边。
• 修复 droste --db ... view，使其可视化指定的数据库。
• 查看器快照使用临时存储，包括在只读安装环境中。
• 为共享同一文件夹的数据库隔离分片、注册表和嵌入缓存。
• 已安装的软件包使用可写的用户数据存储；DROSTE_DB 可覆盖该设置。
• 添加 Windows CI、wheel 内容检查，以及已安装 CLI／查看器／MCP 的冒烟测试。
• 恢复演示首页，并更新竞争定位。

v1.1.6 新增内容

• 修复 PyPI wheel 中 droste view 的打包问题，将可视化器 HTML／模板和公开演示图一并打包到已安装的软件包中。
• 在全新安装环境中验证了三条命令的使用方式： pip install droste-memory、droste index .、droste view。

v1.1.5 新增内容

• 通过在项目扫描中排除 Droste 自身的 .droste/、.tmp/ 和 *.egg-info 目录，修复自索引污染问题。
• 改进小预算上下文打包：优先固定焦点节点的直接调用方／被调用方，再处理次要词法匹配。
• 确保为真正的因果邻居生成精简存根，避免完整上下文无法容纳时重要的虫洞消失。

v1.1.4 版本更新内容

• 通过替换 Python 3.12 专属的 Path.walk() 用法，修复了对 Python 3.10/3.11 的兼容性问题。
• 加强了 MCP Registry 发布流程，确保只有在对应的 PyPI 版本正式发布后，才会发布元数据。
• 改进了 CI 诊断，便于更快地排查多版本发布问题。

v1.1.3 版本更新内容

• 新增公开的 Codex 和 Claude 技能模板，便于 Agent 在端侧采用 Droste。

v1.1.2 版本更新内容

• 在 README/PyPI 描述中添加了 MCP Registry 所有权元数据。
• 添加了用于官方 MCP Registry 发布的 server.json。
• 添加了用于 MCP 注册表发布和可见性检查的手动及定时工作流。

v1.1.1 版本更新内容

• 加强了打包和隐私保护：生成的可视化器 JSON 文件（graph.json、 status.json、context.json）不再包含在源代码分发包中，同时保留公开的 visualizer/demo_graph.json。

v1.1.0 版本更新内容

• MCP 上下文现已按根目录隔离：droste_index_project 会记录当前仓库， 而 droste_get_context / droste_status 会筛选该根目录下的内容，除非 Agent 显式传入另一个 root。
• 如果无法安全推断根目录，多根数据库不再静默混合仓库内容；Droste 会返回明确的警告。
• Windows 命令行输出现已针对 UTF-8 控制台进行保护，避免在较旧的终端编码下因 UnicodeEncodeError 而崩溃。
• 检索排序现已感知查询内容：对于常规实现类查询，运行时代码会获得轻微加权；当查询要求查找测试或文档时，测试和文档仍会完整显示。

许可证

MIT — 参见 LICENSE。