Particles

linkedparticles

linkedparticles.org · docs.linkedparticles.org · PyPI · Apache-2.0

Particles 是供人类和 AI Agent 使用的共享记忆。 每个粒子都是一条主张， 并附带判断它所需的信息：谁说的、出处、时间，以及对方有多确信。事实、观点和记忆 都是主张，并以相同方式记录为粒子。粒子不会被编辑或删除。粒子会被公开地 取代、撤回或质疑。应当多大程度上信任它，是查询时应用的一种视角，绝不会预先写入记录。

linkedparticles 是 Particles 参考实现的 Engine： 你安装后即可实际运行信念存储的包。提供文档、 网页、聊天记录或 Agent 自己的会话笔记；即可获得粒度细化到主张的 信念，每条都带有校准后的置信度、不确定性类型、已解析的主体，以及追溯至精确源字节的来源信息。提出问题，答案会引用构成它依据的信念。任何内容都不会被覆盖，因此你可以询问存储一年前相信什么，以及它后来为何不再相信。

当你的 Agent 出错时，你可以准确看出原因，并从源头修正。

Engine 首先是一个库。HTTP API、CLI、只读 MCP 服务 和常驻守护进程都是它之上的接口。

安装

pip install linkedparticles

Python 3.11+。无存储的 Client 层 linkedparticles-core 会自动安装。

提取内容和生成文字答案时会调用大模型。下面的快速入门使用 Anthropic，任何兼容 OpenAI 的端点也都可用，无论托管还是本地部署 （Ollama、llama.cpp、vLLM）：在 config.yaml 中为每种用途指定其提供方 （命名提供方）。 存入内容、生成会话摘要和结构化查询都不会调用大模型。

六十秒上手

export ANTHROPIC_API_KEY=sk-ant-...
particles db init

# Deposit a source (file, URL, or literal text) into the append-only corpus
particles deposit https://en.wikipedia.org/wiki/Pluto

# Extract claim-granularity beliefs with confidence, subjects, and provenance
particles extract --all-pending

# Ask in natural language; the answer cites the particles behind it
particles query "Why is Pluto not a planet?"

# Health-check the store: contradictions, staleness, orphaned links
particles lint

由于内容不会被覆盖，存储可以重放自身的历史记录。--as-of 是断言时间视角。它回答的是存储在 T 时刻相信什么，以及 后来为何不再相信，而不是 T 时刻世界上实际发生了什么：

particles query "How many planets are in the Solar System?" --as-of 2000-01-01
# → the belief as it stood then, and why it no longer stands: SUPERSEDED,
#   retired 2006-08-24, superseded by "Pluto is a dwarf planet."

你可以在首页查看可交互的信念历史。按步骤开始： 入门指南， 然后阅读按时间点回溯。

将其接入 Agent

particles mcp serve                 # read-only MCP server (stdio), any MCP client
particles init claude-code          # session-start digest, session-end harvest
particles engine serve              # HTTP API, for a shared or remote engine
particles export obsidian ./vault   # also: anki, wiki, logseq, notion, graph, jsonl

它还可以替代参考记忆服务，并作为检索器和工具集接入 LangChain。请参阅 Claude Code 记忆、 替换参考记忆服务， 以及在 LangChain 中使用。

表现如何？

在 LongMemEval（多会话 Agent 记忆基准）上进行测量，并在同一测试框架中将 完整上下文 oracle 和无记忆基准作为对照：

	Recall@40	端到端 QA
Particles 记忆（随附默认设置，top_k 40）	0.969	0.804
完整上下文 oracle（基线，n=148）	—	0.878
无记忆（基准下限）	—	0.047

oracle 和基准下限两行的数据来自同一测试框架中的另一组对照测试，时间为 Particles 行所平均的三次测试的前一天；基准测试页面列出了各行对应的正式报告。

方法、按问题类型划分的细目、对比记忆系统，以及预算匹配测试组（包括 Particles 表现较差的测试组）均见 基准测试页面，页面旁还附有正式报告的 JSON 文件。

安全态势

记忆层是一种输入塑形攻击面：它不只是存放数据，还会影响 Agent 的信念和后续行为，因此，一条被投毒的声明就像一条延迟触发的指令。

三次对抗性审计都审查了这段代码，每次的结论都是 GO-WITH-FIXES。 以下引用的是原始结论。

审计	审计的代码	结论	修复发布于
2026 年 6 月，在代码开放之前：HTTP、CLI 和 MCP 接口、文件系统写入器、出口层、CI 和 wheel 构建	v1.62.0	GO-WITH-FIXES	1.62.1 至 1.63.0；最后一个未解决的问题在 1.128.0 中关闭
2026-10-23：自 v1.62.0 以来的所有变更，包括首次审计时尚未涉及的发布与分发流水线，以及本页的声明	v1.210.2	GO-WITH-FIXES	1.210.3 至 1.211.0
2026-10-24：自第二次审计以来的所有变更、此前的每项审计发现，以及再次审查本页的声明	v1.211.0	GO-WITH-FIXES	1.211.1 至 1.214.0

完成这些修复后，克隆的仓库无法再配置 Particles，也无法提供 MCP 服务所读取的存储；HTTP 调用方无法再让引擎读取其自身磁盘上的文件；网页也无法再向运行于 loopback 地址的引擎发送写入请求，或从未启用密钥的引擎读取数据。持有 PyPI 发布身份的任务不会运行来自软件包索引的任何代码：它会下载构建好的文件，将其与构建任务记录的摘要进行核对，然后运行固定版本的上传操作。并非所有问题都已修复：第二次审计中关于自动停用的部分发现仍未解决，SECURITY.md 对此及其他尚存的限制作了说明。

当前有哪些保障，又有哪些没有：

• 提示词注入只能被遏制，无法被消除。 在基准测试框架之外，所有携带已提交、已存储或已收集文本的模型提示词，都会将指令保留在系统轮次中，并用每次调用单独生成的 128 位随机 nonce 标记的围栏包裹这些文本。测试会查找所有调用模型入口的地方，包括通过传入系统轮次的包装器发起的调用；如果某处尚未分类，或在携带这类文本时未加围栏，测试就会令构建失败。若调用通过其他方式触达模型，例如通过作为值传入的函数，则该测试无法查到。围栏之后还有结构性检查：在解析器中强制执行 JSON 契约，并设置一道关卡，拒绝引用未提供给它的声明的合成文本。这显著提高了防护门槛，但这只是加固，并非免疫。
• 模型没有工具，但它的判定会改变存储内容。 模型从不被提供函数调用能力，它生成的任何内容都不会作为代码或 SQL 运行，也不会被用作抓取目标。尽管如此，它的输出仍会产生影响：它提取的主题名称会成为 Wikidata 搜索词；它的判定会使声明退役（较新的声明更新旧值；同一段落中的声明被重新锚定流程用模型撰写的文字复述；不同可信度来源之间相互矛盾时，可信度较低一方的声明被退役），并将搁置的声明恢复为活动状态，每项操作都会记入事件日志；它提取的信念会写入 Claude Code 的 MEMORY.md，供具有工具的 Agent 读取为指令。注入可以扭曲声明，而被扭曲的声明可能会引导 Agent。
• 每一跳都会检查从已提交内容中获取的 URL。 主机名会被解析，每个地址都会对照阻止列表进行检查，连接也会指向经核验的地址；每次重定向时都会重复这些步骤，从而防止 DNS 重绑定和重定向 SSRF。以子进程运行的两次抓取会固定使用本进程核验过的地址，且都不会自行跟随重定向；git clone 则在没有系统级或全局 git 配置的环境下运行，因此不会对克隆的文件运行任何过滤器驱动程序（包括 git-lfs）。你自行配置的端点（模型提供商、远程引擎、遥测收集器）受 network.egress 设置约束，但不受阻止列表约束，因为 LAN 或本地模型服务是合理的目标。
• 默认拒绝的身份验证，且不会根据输入构造 SQL。 如果未设置 bearer 密钥，引擎就拒绝在非环回地址上绑定；如果通过 uvicorn 命令行启动，它会从命令行读取绑定地址；如果由其他 ASGI 服务启动，且无法读取其绑定地址，也会拒绝启动。之后无论通过哪种路径，引擎都只服务于指定环回主机或 api.allowed_hosts 中列出的环回客户端，从而阻止 DNS 重绑定页面。以操作员权限执行的路由（主题合并、操作员撤回、审核裁决、可信度策略）即使来自环回地址，也需要有效密钥。令牌比较采用恒定时间算法。数据层使用带绑定参数的类型化 ORM 语句；少数几条字面 SQL 语句（架构版本读取和变更日志触发器）都是常量，不接受任何输入。
• 默认使用本地配置，但有三种出站连接默认行为需要了解。 引擎绑定到环回地址，将数据存储在本地 SQLite 文件中，默认关闭遥测，并将 MCP 作为本地启动的 stdio 子进程提供服务。开箱即用时，它还会连接到你配置的模型提供商、在提取过程中用于主题查询的 Wikidata（这些请求会携带提取出的实体名称），以及 Hugging Face Hub，以下载嵌入模型；在出站流量开放期间，进程加载模型时还会检查是否有更新版本。设置仅来自 PARTICLES_CONFIG 指定的文件或 ~/.particles/config.yaml，绝不会来自命令运行所在的目录。存储位置则不同：如果没有指定，particles 命令行和 engine serve 会在各自的运行目录中打开 ./particles.db，而 MCP 服务会打开 ~/.particles/particles.db。将 network.egress 设为 none 或 allowlist，即可限制出站流量。 对残余问题的真正解答在于认识论，而非技术：每个粒子都携带其来源；源可信度是一种读取时的视角，可降低不可信来源的权重，而无需改写任何内容；lint / review 则会将你对矛盾所作的裁定转化为可复用的信任策略。该存储记录的是各个来源说了什么，以及你对它们的信任程度，而非预言机，因此，有毒来源是可见、可降低权重、可撤回的，同时保留完整审计轨迹。

在依赖这些机制之前，我们建议你阅读其局限性，详见 SECURITY.md：默认开放的读取接口、对你存入的内容原样存储（包括机密信息）、会弃用声明的模型裁定、作为相关性筛选而非隔离机制的项目范围、单一操作者信任模型，以及 MCP 写入边界。SECURITY.md 也是报告漏洞的地方；请通过私密渠道报告。

为什么选择 Particles？

大多数检索增强生成系统会在每次查询时从头重新推导知识，处理原始文本块，却没有任何持久记录来保存已学到的内容、置信程度或来源。Particles 采用了不同的方法：它不检索段落，而是存储离散、可引用、可修订的声明（自然语言句子与置信度、来源和不确定性的结构化元数据相配对），让 Agent 的知识积累为可审计的账本，而不是在会话之间消散。在 Core 中，每个语料库条目都必须注明来源，这意味着每条信念都可以追溯到产生它的来源；粒子存储本身则是一个派生视图，可通过重新运行提取器从语料库重建，从而使系统兼具持久性与可复现性。

Particles 标准定义了粒子模式、源语料库模型、提取协议，以及一组操作（deposit、extract、query、lint、review 和 reindex），这些共同构成了 Agent 逐条构建、查询、审计和修订知识的主干。使用这一循环的开发者会将来源存入只追加的语料库，提取具有已解析主体的声明粒度粒子，按有效置信度排序进行查询，检查矛盾和陈旧内容，并将不一致之处审查为可复用的信任策略。由于粒子携带明确的置信度和来源，Particles 可以回答这类查询：找到与某个主体相关的声明，并在保留来源信息的前提下综合这些声明；而不是返回一份认知状态不透明的排序文本块列表。

Particles 是一种精简且可互操作的基础，用于存储声明粒度的 Agent 知识：它比 RDF/SPARQL 等正式本体知识图谱更窄，比增强型 Markdown 更具结构化。将每个粒子锚定到一个主体，才能实现这种精确性：Subject 存储是该标准中真实世界实体的目录，粒子以此为索引，从而让信念对应到规范实体；原则上，这些实体可以映射到外部本体。因此，选择 Particles 的开发者选择的是一种基础，其中每条信念都是拥有自身标识、置信度分数、来源和主体的一等对象，而不是向量空间中的一个位置。

设计原理

Particles 的基础在于保证：任何已经写入的内容都不会被覆盖。Source Corpus 是由所有已提取或可能提取粒子的材料构成的只追加归档，这意味着每份摄取的来源和每条派生主张都会原地累积，而不会取代之前的内容。每个粒子从创建之初就带有来源信息；当某个来源必须以可变模式而非纯只追加模式处理时，系统不会悄然吸收变更：来源位置落在变更区域内的粒子会被标记为 PROVENANCE_STALE，让扰动显而易见，而不是将其掩盖。因此，取代和撤回会沿来源关系图确定性地传播，影响每条起源受到牵连的主张，使账本忠实记录曾经何时提出过什么主张，而绝不会悄然修订过去。

在 Particles 中，信任并非存储记录固有的属性，而是读取时应用的一种视角。原始置信度值以不可变形式存储，在粒子创建时完成校准，此后绝不更改；每次查询变化的是有效置信度，它在查询时计算，而非存储。信任加权、时效衰减和 as-of 时刻都会在查询时针对每位观察者应用，绝不会写回记录。这意味着，随着来源变旧，或生成该粒子的提取器失去可信度，某个信念无需撤回或重写，也会在排名中下降：存储的粒子保持完整，而据此计算出的有效置信度会降低，让过时的信念自然淡出，无需修改底层账本。当 as_of 设为过去的时刻 T 时，查询会沿着主张时间轴评估存储内容（即存储在 T 时相信什么），而非依据任何世界时间有效性维度。这样，同一份不可变语料库就能明确回答关于当前信念和历史信念的问题。

Particles 将矛盾视为知识图谱中的一等公民，而非需要压制的异常。当两个来源或两个主体意见不同时，冲突解决阶梯会呈现一条 INCONSISTENCY 记录以供审查，而不是悄然覆盖任一方，从而在账本中保留两条相互竞争的主张，并让任何下游使用者都能清楚看到分歧。争议状态，即标记某个粒子与一个或多个其他粒子存在张力的属性，必须在读取时计算，绝不存储；与有效置信度一样，它是读取时的视角，而非持久注释。这意味着，随着新粒子到来或旧粒子被取代，任何给定主张的争议状态都会根据图谱的当前状态重新推导，而非沿用早先写入的过时标记。

Particles 中的记忆通过定期自动运行的健康检查机制维护。Lint 操作会检查矛盾、过时主张、孤立页面和缺失的交叉引用，并按计划扫描语料库，让问题成为可见的发现，而非悄然降低信念存储的质量。由于任何内容都不会被覆盖，矛盾也不会被武断裁定，Lint 得以在稳定的基础上运行：它遍历查询所读取的同一份不可变记录，其发现结果会反馈至信任策略审查周期，从而闭合摄取、查询与持续维护账本完整性之间的循环。

架构

Particles 部署围绕两个不同的存储子系统构建：源语料库存储和粒子存储。源语料库存储是仅追加的对象存储，兼容本地文件系统、兼容 S3 的后端或内容寻址存储；语料库条目和快照元数据则以可查询的形式保存，可采用关系型存储或文档存储。这两个子系统共同构成所有操作所依托的持久基础。

Core SDK 同时提供简洁的 Python API 和 CLI，六项核心操作（存入、提取、查询、Lint、重建索引和审核）分别对应参考 SDK 中的一个 CLI 子命令和一个 POST API 端点。因此，开发者可以通过两个对称的接口执行每项操作：适合用于流水线的可编写脚本的命令行，以及适合应用程序集成的编程接口。

从原始来源到一组粒子的过程始于存入：将来源写入仅追加的语料库；随后进行提取，驱动提取流水线。该流水线会选择已注册且适用性规范与存入来源相匹配的最具体提取器；当且仅当没有适用的特定领域提取器时，才会使用通用提取器。粒子进入粒子存储后，查询会按有效置信度排序并检索粒子，Lint 会检查矛盾和过时内容，重建索引会重建派生索引，而审核则会将不一致之处整理成可复用的信任策略。这一流程中的每一步都是离散且有名称的操作，而非隐式副作用，因此开发者可以独立调用任意阶段，并分别观察其输入和输出。

为什么选择 Particles？、设计原理和架构部分是 粒子存储的引用投影，并非人工撰写的文字。每个 标记区块都由 docs/projection/readme.yaml 及与其一同提交的语料库包渲染而成，每个区块下方的尾注 都列出了其依据的确切声明。请编辑清单或底层 粒子并重新渲染，切勿修改标记之间的文字。可以自行检查：python scripts/projection_drift.py 会将语料包还原到 临时存储，重新生成确定性渲染结果；如果任何区块 与其引用的声明不一致，就会失败。

这就是项目在实际使用自己的理念：README 倡导 带来源信息的声明粒度知识，而它本身也正是以这种方式组装而成。

文档

以下所有内容均发布于 docs.linkedparticles.org。

指南	内容
用户指南	存入、提取、查询、按时间点回溯、导出、Agent 集成
运维指南	配置、调优、Lint 和审核、远程引擎、容器、可观测性、故障排查
插件作者指南	编写提取器、导出器和基准测试套件
CLI 参考	每个动词和标志
HTTP API	OpenAPI 合约
基准测试	LongMemEval 结果、方法和比较对象

标准本身（白皮书、技术规范以及规范性 架构、上下文和词汇表制品）位于 linkedparticles.org。

三个代码库

代码库	说明
particles-standard	标准：白皮书、技术规范、规范性 Schema 和 SHACL 工件、符合性测试样例
particles-core-py	Python 客户端层（linkedparticles-core）
particles-engine-py	本代码库：Python 引擎层及接口（linkedparticles）

部署

容器和 Chart 工件位于 deploy/ 下。 该引擎以单写入者服务的形式提供；请参阅 在容器中运行。

贡献

请参阅 CONTRIBUTING.md 和 ARCHITECTURE.md。 贡献需签署开发者来源证明（Developer Certificate of Origin）； 无需签署 CLA。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。