内容
<div align="center">
# Droste
### 将您的代码库视为一个生动的星系 — 并赋予您的代理对其的因果记忆。
Droste 将任何仓库索引到一个分形的、可缩放的符号地图中，将它们用真正的调用 / 导入 / 数据库边缘连接起来，并为代理提供它实际需要的因果切片 — 而不仅仅是关键词匹配。
**本地优先 · 零配置 · 多语言 · MCP 原生**
[](https://pypi.org/project/droste-memory/)
[](https://pypi.org/project/droste-memory/)
[](https://github.com/lorismascio17/droste-memory/actions/workflows/ci.yml)
[](LICENSE)
*缩放出去显示因果网络 — 每个青色弧线都是一个真正的 `语法依赖` 边。[完整飞越（FastAPI）](docs/assets/demo.mp4)*
[快速入门](#快速入门) · [为什么它不同](#为什么它不同) · [它是如何工作的](#它是如何工作的) · [用作MCP服务器](#用作MCP服务器) · [基准测试](#基准测试)
</div>
---
## 快速入门
```bash
# Windows
python -m pip install --upgrade droste-memory
# macOS / Linux
python3 -m pip install --upgrade droste-memory
droste index . # 索引当前仓库
droste view # 在浏览器中打开分形星系
```
安装一次，然后索引和查看。`droste view` 打开一个全屏、60fps 可缩放的您的代码地图 — 滚动以潜入从项目星到文件夹轨道，再到单个函数，带有它们之间的因果边缘发光。
您需要它用于代理而不是眼睛吗？
```bash
droste context "checkout flow" --budget 1500 # 用于LLM的因果上下文切片
```
运行 `droste` 且无参数打印命令面板：
```text
.-----------------------.
.----' | '----.
.---' .-----+-----. '---.
.' .----' | '----. '.
/ .---' .---+---. '---. \
/ .-' .-' | '-. '-. \
| .' .-' .---+---. '-. '. |
| / .' .' | '. '. \ |
| | | | .--+--. | | | |
| --+--------+-----+---+ @ +---+-----+--------+-- |
| | | | '--+--' | | | |
| \ '. '. | .' .' / |
| '. '-. '---+---' .-' .' |
\ '-. '-. | .-' .-' /
\ '---. '---+---' .---' /
'. '----. | .----' .'
'---. '-----+-----' .---'
'----. | .----'
'-----------------------'
DROSTE-MEMORY // 刚性分形径向布局
本地图引擎 v1.1.1-Alpha-Sharded
命令
droste index <path> [--reset]
droste status
droste zoom <symbol_name>
droste context [query] --budget 1500
droste mcp
快速路径：droste context hub_core --budget 1000 | clip
```
---
## 为什么它不同
大多数“代码上下文”工具通过关键词（ctags / ripgrep / repo-maps）或嵌入式余弦（vector-RAG）进行排名。两者都只能返回与查询 *相似* 的内容。
调用者不共享任何令牌的调用者 — 或不同语言中的数据库函数 — 对它们来说是不可见的，但它正是您需要理解或更改代码的内容。
Droste 的优势在于因果图：
- **因果虫洞**。真正的 `语法依赖` 边（调用、导入、继承）双向 — Droste 提供调用者和被调用者，按顺序，在令牌预算内。
- **跨语言桥梁**。其他人做得不好的部分：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 模式）。
---
## 基准测试
自监督评估（黄金 = AST 的真正调用者/被调用者集），相等检索宽度 *k*，真实嵌入，跨 Python + Dart 仓库（`eval/comparative_eval.py`）：
| 结构化检索 | Droste | 向量-RAG核心 | 词法核心 |
| --- | --- | --- | --- |
| 邻居召回率 | **0.94** | 0.18 | 0.42 |
| nDCG@k | **0.65** | 0.10 | 0.29 |
…另外还有数百个真实的因果邻居，两个基线在结构上完全遗漏。这是对检索方法的比较（向量-RAG 和词法搜索的核心），而不是与封装它们的成品进行正面比较。
---
## 它是如何工作的
- **因果图**。每个定义都被解析（Python `ast`；tree-sitter 用于其他语言）为其调用/导入/继承的名称，成为一流的 `语法依赖` 边。跨语言边添加数据库调用（`.rpc`、`.from`、`.functions.invoke`）和字符串字面量名称匹配跨语言。
- **混合种子**。查询通过词汇得分和语义余弦（fastembed `bge-small-en-v1.5`，384-dim）的归一化混合进行匹配，然后图双向扩展种子（被调用者和调用者）。
- **令牌打包器**。结果适合预算，带有LOD降级（完整到合约到骨架）和硬护栏，永远不会在令牌中间剪切代码行。
- **分片持久性**。每个文件一个分片，位于 `.droste/` 下，blake2b 脏跟踪，以便重新索引仅重写更改的内容；原子写入 + 元数据最后写入，因此它是崩溃安全且自我修复的。
---
## 用作MCP服务器
Droste 是一个即插即用的MCP服务器 — AI代理可以调用它作为主要的代码内存，而不是进行盲目文件读取。在您的客户端配置文件中添加以下内容（例如，Cursor、Claude Desktop 或 Codex）：
首先安装或升级PyPI包：
```bash
# 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`：
```toml
[mcp_servers.droste]
command = "droste"
args = ["mcp"]
startup_timeout_sec = 120
```
默认情况下，`droste mcp` 使用Droste的全局本地数据库。对于快速使用和小工作流，这就可以了。对于严肃的多仓库工作，请为每个仓库使用一个数据库，以便每个项目都有隔离的内存，代理可以安全地使用 `reset=true` 重新索引该项目。
`--db` 选项是全局的，因此请将其放在 `mcp` 之前：
```toml
# Windows 示例
[mcp_servers.droste]
command = "droste"
args = ["--db", "C:/Users/you/AppData/Local/Droste/my-project/droste_memory_db.json", "mcp"]
startup_timeout_sec = 120
```
```toml
# macOS / Linux 示例
[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客户端：
```json
{
"mcpServers": {
"droste": {
"command": "droste",
"args": ["mcp"]
}
}
}
```
相同的隔离数据库模式适用于JSON客户端：
```json
{
"mcpServers": {
"droste": {
"command": "droste",
"args": [
"--db",
"/absolute/path/to/droste_memory_db.json",
"mcp"
]
}
}
}
```
在更改MCP配置后重启客户端。在仓库中，请让您的代理调用 `droste_index_project`，然后为因果上下文调用 `droste_get_context`。
主要工具：`droste_index_project`、`droste_get_context`、`droste_status`。
---
## 开发
```bash
pip install -e ".[dev]"
pytest # 确定性回归套件（tests/）
python eval/comparative_eval.py # 检索基准测试 vs 词法和向量核心
```
`tests/` = 不变性 + 并发性（往返、脏预言、打包护栏、跨进程分片竞争）。`eval/` = 性能/质量基准测试。
---
## 状态
**v1.1.1（alpha）**。引擎、多语言 + 跨语言图、CLI、分形可视化和MCP服务器正在运行并经过测试。打包/分发正在成熟 — 问题和PR欢迎（参见 `CONTRIBUTING.md`）。
### 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` 过滤到该根，除非代理传递另一个显式 `root`。
- 多根数据库不再在无法推断安全根时静默混合仓库；Droste返回一个干净的警告。
- Windows CLI 输出被守护以防止 `UnicodeEncodeError` 在旧终端编码上崩溃。
- 检索排名现在是查询感知的：运行时代码为正常实现查询提供轻微的提升，而测试/文档在查询询问时仍然完全可见。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
