priostack

⚡ Priostack 智能体上下文网络（ACN）

通过 MCP 实现零配置、模型无关的长期记忆和多智能体上下文共享。

Priostack ACN 将 Agent 的长期记忆视为一种网络资源，而不是附属于某个大模型供应商的功能。它是一个通过 JSON-RPC 2.0 访问的**模型上下文协议（MCP）**服务，Agent 可以自行注册、维护彼此隔离的上下文空间、存储类型化事实、读取事实，并通过范围受限且可撤销的能力授权与其他 Agent 共享这些事实。

公共服务已上线，地址为 https://priostack.com/mcp（可发现的 Streamable-HTTP MCP 端点；https://priostack.com/acn/rpc 是可用的别名）。

---

🔥 它能为你提供什么

• 🤖 零配置接入 — Agent 通过 noetic.register 自行注册并获取 bearer 令牌。无需控制面板、无需 UI、无需信用卡。
• 🌐 模型无关的记忆 — 同一上下文可供 OpenAI、Anthropic 或本地模型 Agent 使用；记忆与模型解耦。
• 🤝 范围受限的多智能体共享 — 授予另一个 Agent 对某个空间的明确内容权限（read、quote、write、share、export 等），或允许它通过 request_access 请求访问并批准请求。授权可撤销，且仅向前生效。
• 🧠 类型化事实 — 存储 declaration（规则/政策）、observation（测量事实）和 measurement，将“所声称的内容”与“所观察到的内容”区分开来。
• 🔌 原生 MCP — 通过 URL 连接 Claude Desktop、Cursor 或任何 MCP 客户端，也可以使用下方的 SDK。

---

🚀 快速开始（Python）

pip install priostack

from priostack import ACNClient

with ACNClient() as acn:                       # defaults to https://priostack.com/mcp
    acn.register(display_name="my-agent")      # self-register; token captured on the client
    acn.connect()                              # open a session; session id captured internally

    space = acn.create_space(display_name="prod-memory")
    acn.store(space.space_id, objects=[
        {"content": "Refunds over $500 require manager approval.", "type": "declaration"},
        {"content": "Export pipeline latency was 1.8s at 14:02 UTC.", "type": "observation"},
    ])

    hits = acn.fetch(space.space_id, query="refund")   # substring content reader
    for content in hits.contents():
        print(content)

持久保存令牌。 register() 返回一个仅显示一次的 bearer 令牌。请保存它和空间 ID，之后使用 ACNClient(token=...) 重新连接，而不要再次注册。

examples/ 中还有更多可运行示例：多智能体共享、 请求并批准访问、 获取并召回、 撤销并轮换，以及用于 LangChain、CrewAI 和 Claude Agent 的记忆集成。

每个示例都会读取 PRIOSTACK_ENDPOINT，因此只需导出一个变量，就能将它们全部指向可自托管节点、暂存节点或本地节点：

export PRIOSTACK_ENDPOINT=http://127.0.0.1:8091/rpc

---

🧩 Agent 框架快速开始

每个示例都包含完整流程——注册、创建空间、存储、与第二个 Agent 共享、再读取回来——并且都可以独立运行：ACN 调用会实际执行；如果未安装框架（或大模型密钥），则会显示消息并跳过框架部分。

框架	快速开始	展示内容
CrewAI	examples/crewai_quickstart.py	每个团队成员都有自己的 ACN 身份；研究员拥有该空间，并授予写作者 read + quote 权限
LangGraph	examples/langgraph_quickstart.py	持续时间超过图运行的记忆——第 2 次运行会根据第 1 次运行存储的内容作答——随后向审阅者 Agent 授予同一空间的 read 权限
AutoGen	examples/autogen_quickstart.py	拉取握手流程：分析员发现一个已发布的空间，说明理由并请求 read 权限，归档员随后批准请求

pip install priostack
python examples/crewai_quickstart.py          # works with or without crewai installed

---

🤝 多 Agent 上下文共享

所有者向另一个 Agent 授予对某个空间的指定范围访问权限。授权对象是被授权者的 Agent ID（由 register() 返回），被授权者随后必须重新连接，才能获取扩大的权限范围。

# Owner stores knowledge and grants read + quote to a worker agent.
grant = owner.grant_access(space.space_id, worker_agent_id, rights=["read", "quote"])

worker.connect()                       # reconnect to apply the grant
print(worker.fetch(space.space_id, query="refund").contents())

owner.revoke_access(grant.capability_ref)   # immediate, forward-only

更偏好拉取模式？使用者调用 request_access(space_id, rights=["read"])，所有者调用 list_requests() 和 approve_request(request_id)。请参阅 examples/request_and_approve.py。

---

🌍 支持 15 种语言的 SDK

Python 是参考 SDK（位于此仓库根目录，可在 PyPI 上获取）。另外 14 种语言的惯用客户端位于 clients/ 下，各自带有快速入门指南和 README，并且都实现了完全相同的传输协议（clients/SPEC.md）。

语言	路径	HTTP + JSON 技术栈
Python	/ · PyPI priostack	requests
JavaScript (Node ≥20)	clients/javascript	内置 fetch
TypeScript	clients/typescript	全局 fetch（带类型）
Java (Maven)	clients/java	java.net.http + Jackson
Go	clients/go	标准库 net/http
C# / .NET 8	clients/csharp	HttpClient + System.Text.Json
PHP (Composer)	clients/php	curl
Ruby	clients/ruby	标准库 net/http
Rust	clients/rust	reqwest + serde
Kotlin (Gradle)	clients/kotlin	java.net.http
Swift (SwiftPM)	clients/swift	URLSession + Codable
C++17	clients/cpp	libcurl + nlohmann/json
Dart	clients/dart	package:http
Scala	clients/scala	java.net.http + uPickle
Shell	clients/shell	curl + jq

每个客户端都附带两个快速入门：一个单 Agent 版本（注册 → 创建空间 → 存储 → 获取），以及一个共享版本（share_quickstart — 两个 Agent、一个空间、显式授权，然后撤销），因为一个只和自己通信的 Agent 并没有在使用网络。

每个客户端都会解包 MCP 信封、捕获会话 ID、在工具拒绝请求时抛出类型化错误，并复用一个 HTTP 连接。所有 15 个共享快速入门都已针对运行中的 ACN 节点完成端到端测试——包括注册两个 Agent、授权、读取和撤销；每个客户端也都能在 CI 中构建（参见 .github/workflows/ci.yml）。

---

🛠️ 从 MCP 客户端使用（Claude Desktop、Cursor）

ACN 是一个可发现的 Streamable-HTTP MCP 服务，因此 MCP 客户端通过 URL 连接。现成配置位于 examples/mcp_config/。

Claude Desktop（Settings → Developer → Edit Config），通过 mcp-remote 桥接：

{
  "mcpServers": {
    "priostack-acn": { "command": "npx", "args": ["-y", "mcp-remote", "https://priostack.com/mcp"] }
  }
}

Cursor（通过 URL 原生连接远程 MCP）：

{ "mcpServers": { "priostack-acn": { "url": "https://priostack.com/mcp" } } }

自行检查服务发现：

curl -s https://priostack.com/mcp -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools | length'

---

📖 API 参考（JSON-RPC 2.0）

端点：https://priostack.com/mcp（别名：https://priostack.com/acn/rpc）。

每次调用都是一个 tools/call：

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"noetic.store","arguments":{ "sessionId":"...", "space":"space-1", "objects":[...] }}}

响应会将结果封装为文本；使用 JSON.parse(response.result.content[0].text) 解析，即可获得 {ok, outcome, data, detail?}。当 ok:false 时，outcome 的值为 not-found、invalid-query、capability-denied、policy-denied、 requires-governance、stale-base、integrity-fault、conflict、capacity-exhausted、 not-implemented。（上述所有 SDK 都会为你完成解析和错误映射。）

方法	用途	关键参数	备注
noetic.register	为 Agent 自行注册	displayName	返回 data.token（仅显示一次）
noetic.connect	开启会话	token、maxResponseTokens	返回 data.SessionID（PascalCase）
noetic.create_space	创建上下文空间	sessionId、displayName、defaultRights	返回 data.spaceId
noetic.store	保存类型化事实	sessionId、space、objects[]	type ∈ declaration | observation | measurement
noetic.fetch	读取已存储的内容	sessionId、space、query、limit	子串筛选；这是读取工具
noetic.grant	授予限定范围的访问权限	sessionId、subjectPrincipal、resource、rights[]、worldMutation	空间参数为 resource；被授权者需重新连接
noetic.revoke	撤销一项能力	sessionId、capabilityRef	立即生效，且仅影响未来
noetic.request_access	请求访问权限	sessionId、space、rights[]、reason	权限参数为 rights
noetic.list_requests	列出待处理请求	sessionId	所有者端
noetic.approve_request	批准请求	sessionId、requestId、rights[]	创建授权
noetic.discover	列出公开空间	query、limit	无需会话
noetic.metrics	查看会话用量	sessionId	账户和空间指标
noetic.rotate_token	生成新令牌	sessionId	使旧令牌失效
noetic.disconnect	结束会话	sessionId	保留持久化事实

fetch 与 query 的区别： noetic.fetch 返回已存储的内容（按子串筛选）。noetic.query 是对记忆进行几何偏差探测，而非读取内容；不要用它来读取事实。

总计约有 40 个工具；每个 SDK 都提供通用的 call(method, arguments) 备用入口，以调用未显式封装的工具。

---

📚 文档

什么是 Agent Context Network	概念、权限模型、常见问题
API 与工具参考	所有 MCP 工具，按用途分组
集成指南	Claude、Cursor、LangChain、CrewAI、兼容 OpenAI 的 Agent
开发者中心	MCP、Python 和 HTTP 入口
教程	分步指南
免费方案和限制	免费使用：每个 Agent 账户每月可使用 5 个空间、500,000 个对象和 500,000 次查询

---

🧪 开发

pip install -e ".[dev]"
pytest                     # unit tests (mocked transport, no network)
ruff check src tests
./scripts/check-links.sh   # every link in the docs still resolves

CI（GitHub Actions）会运行 Python 测试套件、构建并进行类型检查（涵盖每种语言的客户端），并在每个拉取请求中检查文档链接。

---

📄 许可证

MIT。请参阅 LICENSE。