agent-rag
它是什么？
Agent-rag是按项目逻辑组织的用户故事、契约、规范和手册等文档的确定性的、每个客户端的事实来源。原始字节存储在内容寻址的对象存储中；SQLite是一个可重建的索引，而不是事实的来源。
它不是什么
印迹是记忆点；Agent-rag从文件中检索答案。Agent-rag不是聊天机器人：它提供确定的目录和文档读取操作，而不是自主对话。在v1中，它不是LLM或嵌入索引。
安装
全局安装，以便MCP适配器可以解析 agent-rag-mcp 从它的 PATH：
npm install --global agent-rag-mcp
这个 rag 目前可用的命令有：
rag init—初始化命名空间数据库和对象存储。rag add <path>—摄取文件并同时将其字节复制到对象存储，因此OneDrive/Files-On-Demand eviction不会丢失摄取的文档。rag import <dir>—从目录中获取文件。rag ls—列出所选命名空间中的活动文档。rag rm <document-id>—逻辑上退出文档并保留其历史记录。rag relabel <document-id> --label <text>-替换一个文档的存储标签。rag entity rename <from> <to>-纠正项目中的实体密钥。rag review list-列出等待人工决策的版本对。rag review link <from> <to> --type <conflicts_with|same_entity>-用注释记录版本之间的人工链接。rag status—显示命名空间的计数。rag doctor—验证注册对象的完整性，并报告丢失的对象、孤立blob或临时文件。rag backup --to <dir>—备份清单和对象存储。rag restore --from <dir>—恢复该根目录下的备份。rag reindex—根据清单和对象重新构建数据库。rag rehash-预览重新计算的哈希存储版本；rag rehash --apply在一个事务中写入更改的哈希事实。先预览，然后备份rag backup --to <backup-dir>在应用之前。rag rehash --apply写manifest.json在提交数据库事务之前。在该窗口中的中断可能会使清单先于数据库；重新运行rag rehash --apply或者跑步rag reindex收敛到要求的事实。
CLI输出
交互式终端将文档列表呈现为对齐的列，并将其他支持的结果呈现为简明摘要。当输出是管道输出时，命令保留单行JSON信封。集 RAG_FORMAT=json 或者 RAG_FORMAT=pretty 覆盖终端检测；无效的值退回到自动检测。 rag --help 在终端上默认为原始用法文本，而 RAG_FORMAT=json 为解析遗留帮助输出的脚本恢复其JSON信封。集 NO_COLOR （任何值，包括empty），在不改变输出布局的情况下禁用ANSI样式。
rag ls 包括每个文件的 documentId． 复制该值以重新标记相同的文档：
rag ls
rag relabel <document-id> --label "replacement label"
结构化文件可以使用 .yaml， .yml， .json，或者 .jsonl;每个结构化文件从其解析的数据树中产生部分。YAML使用YAML 1.2核心模式，所以像 yes 和 on 保持字符串，未加引号的时间戳保持字符串。
内容身份
结构化JSON、JSONL和YAML都是从紧凑的规范化JSON中散列出来的，用于它们解析的数据树，没有格式前缀。他们的 doc_version 行用 content_kind='structured' 和 hash_version=2;因此，等价树可以跨格式和键顺序共享内容散列。其他格式保留现有的规范化提取文本散列并使用 content_kind=NULL 与 hash_version=1． 现有的版本行保持在版本1，并具有空内容类型，直到使用 rag rehash;修复不会重写存储的对象字节，也不会跳过不能进行常规散列的结构化文档。
默认的知识库根为 %USERPROFILE%\.rag\． 每个客户端都有自己的 rag.db 下 .rag\clients\<client>\;项目在客户端中是合乎逻辑的，并由 project_id． 命名空间就是pair (client, project)． 默认情况下, failClosed 是 true;如果没有名称空间，则允许读取 failClosed 设为 false，写入到保留的 default/default 名称空间。Tier 3人工审核队列可通过 rag review list.
rag add 是幂等的吗 sha256：再次添加相同的字节将返回 {namespace, result} 信封 result.status 设置为 "unchanged" 也不会产生新的版本。不同的散列创建新的散列 doc_version 不删除前一个。删除是一个逻辑墓碑；版本历史被保存。 label 是重新摄取所匹配的，因此重新标记将文档从相同源路径的未来导入中分离出来，然后该路径将作为新文档出现。
MCP
在适配器配置中注册两个独立的服务器进程（本例使用公共的） mcpServers 格式)。取代 /path/to/rag-data 带绝对存储路径：
{
"mcpServers": {
"agent-rag-orchestrator": {
"command": "agent-rag-mcp",
"args": [],
"env": {
"RAG_ROOT": "/path/to/rag-data",
"RAG_CAPABILITIES": "find"
}
},
"agent-rag-explorer": {
"command": "agent-rag-mcp",
"args": [],
"env": {
"RAG_ROOT": "/path/to/rag-data",
"RAG_CAPABILITIES": "find,read"
}
}
}
}
编排器只接收 rag_find，它返回引文和有界摘录。资源管理器也接收到 rag_read，它从引文中读取有界文本。将它们分开使用最小特权。服务器读取 RAG_ROOT 定位知识库和 RAG_CAPABILITIES 决定宣布哪些工具。
扩展增加了 rag 部分向代理系统提示符描述命名空间和委托规则；该部分不包含客户端、项目或路径值。集 RAG_PROMPT=off （正是这个值）来抑制它；任何其他值，包括unset，都会保留它。
命名空间在每个 rag_find 或者 rag_read 调用;它不是来自环境。例如，包括 "namespace": {"client":"acme","project":"research"} 在每个工具调用的参数中。不要配置 RAG_CLIENT 或者 RAG_PROJECT 作为每个调用名称空间的替代品。
要求
- Node.js >= 22.13。
- 这个
.mts运行的源文件--experimental-strip-types --experimental-sqlite. npm run build使用esbuild（每个文件）构建每个源文件。npm test运行Node的测试node:test.npm run typecheck运行TypeScript类型检查而不输出文件。
已知的限制
版本0.1.0没有嵌入或Tier 2；扫描的pdf通过OCR。文档解析在具有512 MB V8堆帽的子进程中运行。
设计文档
许可证
麻省理工学院。