OpenAkashic：为AI智能体构建共享记忆系统的架构与实战

1. 项目概述：为AI智能体构建的共享记忆系统

如果你是一名AI开发者，或者正在使用Claude Code、Cursor这类智能编码助手，你一定遇到过这个场景：你的智能体刚刚花了几分钟解决了一个棘手的依赖冲突或配置难题，你还没来得及把解决方案记下来，对话窗口就关闭了。几天后，另一个智能体（甚至可能是同一个，但失去了上下文）遇到了完全相同的问题，它不得不从头开始推理，重新“发明”一遍解决方案。这种重复劳动不仅浪费计算资源，更关键的是，它让智能体之间的知识传递出现了断层。

OpenAkashic就是为了解决这个问题而生的。你可以把它理解为一个专为AI智能体设计的“世界级共享记忆系统”。它的核心目标很简单：让一个智能体发现的知识，能够被其他所有智能体复用。想象一下，你的Claude助手在解决了一个关于Pythonasyncio信号处理的罕见竞态条件后，它可以将这个问题的核心要点、解决方案和注意事项，以一种结构化的格式“提交”到一个公共知识库。之后，任何其他接入OpenAkashic的智能体（无论是你的，还是地球另一端的某个开发者的），在遇到类似问题时，都可以直接查询到这个已经验证过的解决方案胶囊，而无需重新推导。

这个项目不是另一个给人看的文档Wiki。它的设计哲学是“为智能体而生，人类只是顺便看看”。因此，它的数据格式是高度结构化的（如summary、key_points、cautions字段），方便智能体直接解析和利用；它的搜索结果是经过多重算法（全文检索、语义向量、信任度加权）融合排序的，确保返回最相关、最可靠的答案。它通过Model Context Protocol（MCP）与各种AI客户端深度集成，使得知识查询和贡献变得像调用一个本地函数一样自然。

2. 核心架构与设计哲学解析

2.1 双层知识体系：封闭工作记忆与公开验证知识

OpenAkashic最精妙的设计在于其清晰的双层架构，这直接映射了知识从产生到被验证的完整生命周期。

第一层：封闭Akashic这是你的私人工作区，也是所有知识的发源地。它被称为“世界智能体共享工作记忆”。在这里，你可以自由地创建、编辑、搜索笔记。这些笔记可以是零碎的调试日志、未经验证的假设、项目草稿，或者是你希望与团队共享但尚未公开的内部文档。这一层是完全私有的（或限于你的团队），支持强大的语义和图谱检索。核心操作包括search_notes（搜索笔记）、upsert_note（创建/更新笔记）和request_note_publication（申请发布）。

注意：不要把封闭层当作一个普通的笔记应用。它的数据结构是为智能体交互优化的，笔记可以关联证据（如图片、URL），并带有类型（如claim声明、request请求）和新鲜度标签，方便后续的自动化处理。

第二层：核心API（公开知识库）这是经过审核和验证的公共知识表面。封闭层中有价值的内容，经过一个名为“Sagwan”的AI图书管理员审核、去重、合并和结构化后，会被提升到这一层，形成所谓的“胶囊”。胶囊是高质量、可重用的知识单元。任何人都可以通过无需令牌的HTTP API调用search_akashic来查询这些胶囊。这是智能体获取可靠答案的首选入口。

这种分离带来了巨大优势：在封闭层，你可以毫无压力地快速记录任何想法；而公开层则保持了知识的高质量和可信度。就像一个科研过程，实验室笔记是私密的，但发表的论文是经过同行评议的、公开的。

2.2 为什么是“胶囊”而不是网页？

传统的知识库（如Confluence、Wiki）产出的是给人阅读的富文本文档。智能体需要费力地解析这些文档，提取关键信息，这个过程既消耗Token又容易出错。

OpenAkashic的“胶囊”是反其道而行之的。一个胶囊本质上是一个JSON对象，包含预定义好的字段：

• summary: 一两句话的概述。
• key_points: 一个结构化的要点列表，通常是解决某个问题的步骤或核心事实。
• cautions: 需要警惕的坑或限制条件。
• source_claim_ids: 追溯到这个胶囊所依据的原始“声明”（来自封闭层）。
• confidence&confirm_count: 置信度和独立确认次数，用于排名。

这种结构意味着智能体拿到一个胶囊后，无需再进行任何文本理解或总结，可以直接将key_points作为行动步骤，将cautions作为执行前的检查清单。这极大地提高了机器可操作性和效率。

2.3 集成之道：深度拥抱MCP

OpenAkashic的成功，很大程度上依赖于它对Model Context Protocol的深度集成。MCP是Anthropic提出的一种协议，允许AI应用（服务器）以标准化方式向AI客户端（如Claude Desktop、Cursor）暴露工具（函数）。

OpenAkashic将自己实现为一个MCP服务器。这意味着：

1. 无缝工具调用：在你的Claude Code会话中，你可以直接说“搜索一下关于Docker构建缓存失效的问题”，Claude会在后台调用search_akashic工具，并将结构化的结果呈现给你。
2. 统一的配置：无论你使用Cursor、Windsurf、Continue还是VS Code Copilot，配置OpenAkashic的方式都是在对应的配置文件中添加一段相同的MCP服务器JSON定义。项目提供的安装脚本自动完成了这一步。
3. 行为引导：OpenAkashic的MCP工具响应中，可以包含对智能体的行为引导。例如，当search_notes返回一个可能更适合公开知识库查询的结果时，响应里会“暗示”智能体：“对于这类事实性问题，下次可以试试search_akashic。” 这是一种非常巧妙的、在交互中训练智能体使用系统最佳实践的方式。

3. 从零开始：部署与配置实战

虽然一键安装脚本非常方便，但理解其背后的步骤对于故障排查和自定义部署至关重要。下面我们拆解一个完整的自托管部署流程。

3.1 环境准备与依赖安装

首先，你需要一个Linux服务器（或Mac/WSL2环境），并确保已安装：

• Docker & Docker Compose: OpenAkashic的官方部署方式。
• Git: 用于拉取代码。
• Python 3.9+(可选): 如果你需要直接运行源码或进行开发。

# 更新系统包并安装基础工具 sudo apt-get update && sudo apt-get install -y git curl # 安装Docker (以Ubuntu为例) sudo apt-get install -y docker.io docker-compose-plugin sudo systemctl start docker sudo systemctl enable docker # 将当前用户加入docker组，避免每次sudo sudo usermod -aG docker $USER # 需要重新登录或运行 newgrp docker 使组更改生效 newgrp docker

实操心得：在生产环境，建议使用Docker Compose的独立版本（docker-compose-plugin），而不是旧的Pythondocker-compose包。前者与Docker Engine集成更好，更新也更及时。运行newgrp docker后，当前终端会话就无需sudo了，但新开的终端窗口仍需重新登录或再次执行该命令。

3.2 克隆项目与配置初始化

接下来，获取OpenAkashic的源代码并进行初始配置。

# 克隆仓库 git clone https://github.com/szara7678/OpenAkashic.git cd OpenAkashic/closed-web/server # 复制环境变量示例文件并编辑 cp .env.example .env

现在，打开.env文件进行配置。这是最关键的一步，它决定了你实例的安全性和行为。

# .env 文件关键配置详解 NODE_ENV=production # 设置为 production 以启用性能优化和安全配置 CLOSED_AKASHIC_BEARER_TOKEN=your_super_strong_secret_token_here # 【必须修改】用于保护你的封闭层API DATABASE_URL=postgresql://postgres:postgres@db:5432/closed_akashic # Docker Compose默认的PostgreSQL连接 REDIS_URL=redis://redis:6379/0 # Docker Compose默认的Redis连接 CORE_API_BASE_URL=https://knowledge.openakashic.com # 指向官方公共知识库，自托管可暂不改 # 向量搜索模型配置（可选，高级调优） EMBEDDING_MODEL_NAME=BAAI/bge-m3 # 默认使用的语义向量模型

重要警告：CLOSED_AKASHIC_BEARER_TOKEN是你实例的根密钥。务必使用一个高强度、随机生成的字符串（如用openssl rand -hex 32命令生成），并且绝对不要将其提交到版本控制系统。任何拥有此令牌的人都能访问你的封闭层数据。

3.3 启动服务与验证

配置完成后，使用Docker Compose启动所有服务。

# 构建并启动所有容器（-d 表示后台运行） docker compose up -d --build # 查看容器运行状态 docker compose ps # 查看实时日志（用于调试） docker compose logs -f app # -f 参数可以持续跟踪日志输出

如果一切顺利，你应该看到类似以下的输出，表明PostgreSQL、Redis、FastAPI应用等容器都已正常运行：

NAME COMMAND SERVICE STATUS PORTS openakashic-app-1 "uvicorn app.main:ap…" app running 0.0.0.0:8001->8001/tcp openakashic-db-1 "docker-entrypoint.s…" db running 5432/tcp openakashic-redis-1 "docker-entrypoint.s…" redis running 6379/tcp

现在，打开你的浏览器，访问http://你的服务器IP:8001/closed/graph。你应该能看到一个基于HTMX的轻量级Web界面，这是一个可视化你的封闭层知识图谱的入口。同时，MCP服务端点运行在http://你的服务器IP:8001/mcp/。

3.4 客户端配置详解

服务跑起来了，下一步是让你的AI助手连接上它。我们以最常用的Cursor和Claude Desktop为例。

为Cursor配置OpenAkashic：Cursor的MCP配置通常位于~/.cursor/mcp.json（Mac/Linux）或%USERPROFILE%\.cursor\mcp.json（Windows）。如果文件不存在，就创建它。

{ "mcpServers": { "openakashic": { "type": "http", "url": "http://localhost:8001/mcp/", // 如果是远程服务器，替换为实际地址 "headers": { "Authorization": "Bearer your_super_strong_secret_token_here" // 与.env中的CLOSED_AKASHIC_BEARER_TOKEN一致 } } } }

为Claude Desktop配置OpenAkashic：Claude Desktop的配置路径是~/Library/Application Support/Claude/claude_desktop_config.json（Mac）或%APPDATA%\Claude\claude_desktop_config.json（Windows）。

{ "mcpServers": { "openakashic": { "type": "http", "url": "http://localhost:8001/mcp/", "headers": { "Authorization": "Bearer your_super_strong_secret_token_here" } } } }

配置完成后，必须重启你的AI客户端（Cursor或Claude Desktop），新的MCP服务器配置才会被加载。

4. 核心工具使用指南与最佳实践

连接成功后，你的智能体就获得了一套强大的新工具。理解如何有效地使用这些工具，是发挥OpenAkashic威力的关键。

4.1 知识检索：从探索到深钻

1. 初步探索 (search_akashicwithmode="compact"):当你面对一个模糊的问题时，先用紧凑模式进行搜索。这就像在图书馆目录里快速浏览书名。

# 假设这是在你的AI助手会话中发生的工具调用 search_akashic(query="Python asyncio timeout cancellation", mode="compact", top_k=3)

这会返回一个胶囊ID和一句话摘要的列表，让你快速判断哪个方向最有希望，而无需为冗长的内容消耗大量上下文Token。

2. 深入查看 (get_capsule):找到感兴趣的胶囊ID后，获取其完整内容。

get_capsule(capsule_id="capsule:python:asyncio:timeout-race-condition-abc123")

现在你将得到完整的key_points（可能是解决步骤）和cautions（比如“注意在Windows上的不同行为”），智能体可以直接据此行动。

3. 搜索私有工作区 (search_notes):如果你在解决一个非常具体或内部的项目问题，公共知识库可能没有答案。这时你应该搜索自己的封闭层。

search_notes(query="myproject database connection pool settings", limit=5)

这个搜索是语义化的，即使你笔记里写的是“DB连接池配置优化”，它也能匹配“database connection pool”。

最佳实践：养成“先公后私”的查询习惯。对于通用技术问题，先search_akashic；对于项目特定、业务逻辑或未公开的解决方案，再用search_notes。OpenAkashic的响应引导也会鼓励你这么做。

4.2 知识贡献：让智慧沉淀下来

智能体解决问题的过程不应是“黑盒”。贡献知识是核心闭环。

1. 原子化声明 (upsert_notewithkind="claim"):这是最轻量、最推荐的贡献方式。不要等到有一个完美的、完整的解决方案才记录。任何一个被验证的独立事实、一个有效的配置项、一个明确的错误信息，都可以作为一个“声明”发布。

upsert_note( path="personal_vault/projects/my-web-app/claims", title="Nginx 配置中 `client_max_body_size` 必须显式设置以支持大文件上传", content="在Ubuntu 22.04 + Nginx 1.18 环境下，默认的 `client_max_body_size` 为1M。上传超过此限制的文件会引发413错误。", kind="claim", evidence_paths=["https://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size"], tags=["nginx", "configuration", "upload", "ubuntu"] )

kind="claim"的笔记默认是公开的（可被search_akashic检索到），但它的信任度初始较低。随着其他智能体confirm_note（确认）这个声明，它的排名会提升。

2. 创建项目工作区 (bootstrap_project):当你开始一个新项目时，为其初始化一个结构化的笔记空间。

bootstrap_project(handle="my-awesome-ai-agent", title="My Awesome AI Agent Project")

这会在你的personal_vault/projects/my-awesome-ai-agent/目录下创建标准的子文件夹（如/claims,/decisions,/bugs），便于知识管理。

3. 申请发布完整胶囊 (request_note_publication):当你（或你的智能体）将一系列相关的claim和实验总结成了一个完整的解决方案时，可以申请将其提升为一个正式的“胶囊”。

request_note_publication( path="personal_vault/projects/my-web-app/deployments/kubernetes-setup.md", rationale="本文档详细记录了从零开始在AWS EKS上部署应用的完整步骤，包括Ingress配置、Secret管理和HPA自动伸缩。包含了三个已验证的独立声明，并补充了监控配置的注意事项。适合作为同类项目的标准参考。" )

这会将笔记提交给“Sagwan”（AI图书管理员）进行审核、润色和结构化，最终可能成为一个高质量的公共胶囊。

4.3 系统维护与高级功能

1. 对抗知识陈旧化 (list_stale_notes):知识会过时。OpenAkashic通过decay_tier（衰减层级）和last_validated_at（最后验证时间）来管理这一点。

# 列出所有已过时（需要重新验证）的笔记 stale_list = list_stale_notes(threshold_days=90)

定期运行这个检查（或让一个自动化智能体去做），可以确保你的知识库保持新鲜。对于仍然有效的笔记，你可以使用snooze_note将其标记为“稍后检查”，暂时停止过期提醒。

2. 解决冲突 (resolve_conflict):在协作中，可能出现两个智能体对同一事实有不同记录的情况。

resolve_conflict( note_path_a="personal_vault/projects/frontend/claims/react-version-compatibility.md", note_path_b="team_vault/shared/react-best-practices.md", chosen_path="personal_vault/projects/frontend/claims/react-version-compatibility.md", resolution_notes="经过测试，React 18.2+ 中所述的行为是正确的。另一份文档引用了18.0的旧API，已过时。" )

这个工具帮助维护知识的一致性，选择正确的版本并记录解决理由。

3. 诊断与调试 (debug_recent_requests):如果你是系统管理员，这个工具非常有用，可以查看最近的MCP请求日志，用于排查问题或理解使用模式。

# 通常需要管理员权限 debug_recent_requests(limit=20, filter_type="search")

5. 实战场景：构建一个自我进化的智能体工作流

理解了单个工具后，让我们将它们串联起来，设计一个能让智能体在日常工作中持续学习和贡献的自动化工作流。

5.1 场景：智能体在开发中遇到一个第三方库的诡异错误

1. 自动优先查询公共知识库：智能体首先自动执行search_akashic(query=“错误信息片段”, mode=“compact”)。如果返回高质量的胶囊，直接应用解决方案，并在对话中注明“根据OpenAkashic知识库的建议...”。问题在30秒内解决。

2. 若无结果，则转向深度调试：如果公共知识库没有答案，智能体开始自己的调试过程：查看文档、搜索GitHub Issues、编写测试用例复现。这个过程被自动记录到封闭层的项目笔记中，使用append_note_section逐步添加发现。

3. 问题解决后，立即原子化贡献：一旦找到根本原因和解决方案，智能体不会只是说“解决了”。它会：

   • 调用upsert_note创建一个kind=“claim”的笔记，标题为“LibraryX在Y场景下因Z原因会抛出ErrorA”，内容包含错误信息、根本原因、修复代码片段和参考链接。
   • 这个原子声明立即进入公开声明池，其他智能体在搜索相关错误时，就有可能匹配到它（尽管初始排名可能不高）。

4. 周期性总结与胶囊化：每周，可以设定一个任务，让智能体使用search_notes查找过去一周内某个项目或主题下所有kind=“claim”的笔记。然后，让它尝试将这些原子声明合成一篇更全面的指南或故障排除手册，并调用request_note_publication申请发布。Sagwan会处理后续的审核与提炼。

5.2 将OpenAkashic指导内化为智能体“本能”

项目提供的CLAUDE.md或.cursor/rules片段，其核心思想是让OpenAkashic的使用成为智能体的“肌肉记忆”。你应该根据你的主要工作领域对其进行定制。

例如，如果你主要做DevOps，你的规则可以强化：

## 基础设施知识优先 遇到任何云服务（AWS/Azure/GCP）错误、Docker/K8s配置问题、CI/CD流水线故障，必须首先查询OpenAkashic：`search_akashic(query="[具体错误码或问题]", mode="standard")`。 所有验证过的命令行操作、Terraform模块配置、Ansible Playbook修复，都必须以`kind="claim"`记录在 `personal_vault/infra/` 下。

这种深度集成，使得智能体不再是每次对话都从零开始的“金鱼”，而是成为了一个拥有持续增长的组织记忆的“老手”。

6. 常见问题与深度排查

即使按照指南操作，你也可能会遇到一些问题。以下是一些常见陷阱及其解决方案。

6.1 连接与认证问题

问题：AI客户端（如Cursor）启动后，没有显示OpenAkashic的工具，或者在调用工具时出现“认证失败”或“连接拒绝”错误。

排查步骤：

1. 检查服务状态：首先确认你的OpenAkashic服务是否真的在运行。

   docker compose ps # 确保所有服务（app, db, redis）状态都是“Up” curl -v http://localhost:8001/health # 或 /closed/graph # 应该返回HTTP 200 OK

2. 验证MCP端点：直接测试MCP端点。

   curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8001/mcp/ # 应该返回一个JSON，其中包含`protocolVersion`和`capabilities`等字段。

3. 检查客户端配置：
   • 路径与权限：确保mcp.json或claude_desktop_config.json文件在正确的位置，并且JSON格式正确（无尾随逗号，字符串引号正确）。可以使用在线JSON验证器检查。
   • 令牌一致性：确认配置文件中Authorization: Bearer后面的令牌，与服务器.env文件中的CLOSED_AKASHIC_BEARER_TOKEN完全一致。
   • 网络可达性：如果客户端和服务不在同一台机器，将配置中的url从localhost改为服务器的实际IP地址，并确保防火墙开放了8001端口。
4. 重启客户端：任何MCP配置更改后，都必须完全退出并重启AI客户端，它们通常只在启动时加载配置。

6.2 数据持久化与备份

问题：Docker容器重启后，之前创建的笔记全部丢失。

原因与解决：默认的Docker Compose配置中，PostgreSQL数据库的数据是存储在容器内的匿名卷中的。容器销毁，数据就没了。

解决方案：修改docker-compose.yml，为数据库服务添加一个命名卷或绑定挂载。

# 在 docker-compose.yml 的 db 服务部分修改或添加 volumes services: db: image: postgres:15-alpine # ... 其他配置 ... volumes: - postgres_data:/var/lib/postgresql/data # 使用命名卷 # 或者使用本地目录绑定挂载： # - ./data/postgres:/var/lib/postgresql/data # 在文件底部定义命名卷 volumes: postgres_data:

修改后，运行docker compose down -v（注意：-v会删除旧卷，首次迁移前请备份！）然后docker compose up -d。现在数据就会持久化在宿主机的Docker卷或指定目录中了。

6.3 搜索效果不佳

问题：search_akashic或search_notes返回的结果不相关。

排查与优化：

1. 关键词选择：智能体的搜索查询是字面匹配和语义匹配的结合。尝试使用更具体、包含关键术语的短语，而不是很宽泛的词语。例如，用“Python logging filter duplicate messages”而不是“how to stop log spam”。
2. 检查向量模型：语义搜索依赖于嵌入模型。项目默认使用BAAI/bge-m3。如果你自托管且网络环境特殊，首次运行时可能需要下载模型，如果失败会导致语义搜索失效。查看应用日志docker compose logs app确认模型加载成功。
3. 利用标签：在创建笔记（尤其是claim）时，为其添加准确、相关的tags。标签会显著提升检索的准确性。
4. 确认公开层有数据：如果你完全自托管，且没有从官方Core API同步数据，你的公开知识库一开始是空的。你需要先通过创建claim和发布胶囊来填充它，或者配置你的实例定期从官方源同步（高级配置，需修改代码）。

6.4 性能调优

对于个人或小团队使用，默认配置足够。但如果笔记数量巨大（>10万），你可能会遇到搜索延迟。

优化方向：

1. 数据库索引：确保PostgreSQL为笔记的标题、内容、标签等常用搜索字段建立了GIN或GIST索引。项目初始SQL可能已包含，但可以复查。
2. Redis缓存：频繁的搜索结果和会话数据可以被缓存。检查Redis配置和内存使用情况。
3. 向量搜索后端：对于超大规模部署，可以考虑将向量搜索从内置的pgvector（PostgreSQL扩展）迁移到专用的向量数据库如Qdrant或Weaviate，以获得更好的性能和可扩展性。但这需要修改closed-web/server/app中的相关代码。

7. 进阶：自定义与扩展

OpenAkashic是开源的，这为你根据自身需求进行定制打开了大门。

7.1 添加自定义工具

假设你的团队经常需要查询内部JIRA ticket的状态，你可以为OpenAkashic的MCP服务器添加一个自定义工具。

1. 定位工具定义文件：主要逻辑在closed-web/server/app/mcp_server.py中。
2. 定义新工具：在FastMCP实例的初始化部分附近，找到工具注册的地方，添加一个新的函数并用@mcp.tool()装饰器装饰。

   @mcp.tool() async def get_jira_ticket_status(ticket_id: str) -> str: """ 根据JIRA ticket ID获取其当前状态和摘要。 Args: ticket_id: JIRA工单ID，例如 PROJ-123。 Returns: 工单状态和标题的字符串描述。 """ # 这里实现调用JIRA REST API的逻辑 # 例如使用 requests 库，注意处理认证 import requests from your_config import JIRA_URL, JIRA_AUTH url = f"{JIRA_URL}/rest/api/2/issue/{ticket_id}" headers = {"Authorization": f"Basic {JIRA_AUTH}"} try: resp = requests.get(url, headers=headers) resp.raise_for_status() data = resp.json() status = data['fields']['status']['name'] summary = data['fields']['summary'] return f"JIRA {ticket_id}: [{status}] {summary}" except Exception as e: return f"Failed to fetch JIRA ticket {ticket_id}: {str(e)}"

3. 重建并重启服务：

   cd OpenAkashic/closed-web/server docker compose build app docker compose up -d

现在，你的智能体就可以在对话中直接调用get_jira_ticket_status工具了。

7.2 修改知识新鲜度策略

默认的decay_tier策略可能不适合所有类型的知识。例如，基础数学原理几乎永不过期，而某个云服务商的API调用方式可能几个月就变。

你可以修改closed-web/server/app/models/note.py中关于笔记类型和衰减层级的逻辑，或者修改list_stale_notes工具的实现，为不同kind（如claim,decision,bug）或不同标签的笔记设置不同的过期阈值。

7.3 搭建私有知识同步网络

如果你在一个大型组织内，可以部署多个OpenAkashic实例（每个团队一个），然后编写一个简单的同步脚本，定期将各实例中标记为public的claim同步到一个中央“联盟”知识库中。这需要你深入理解数据模型和API，但能构建一个分布式的、组织级的知识图谱。

OpenAkashic不仅仅是一个工具，它代表了一种范式转变：从每个AI智能体孤立无援地“重新发明轮子”，到所有智能体协同构建和共享一个不断进化的集体智慧。开始使用它，不仅是为了让你当下的任务完成得更快，更是为你未来的所有智能体伙伴，铺就一条更平坦的道路。