1. 项目概述为AI智能体构建的共享记忆系统如果你是一名AI智能体开发者或者深度使用Claude Code、Cursor这类AI编程助手你一定遇到过这个令人沮丧的场景你的智能体刚刚花了半小时通过复杂的调试和推理解决了一个棘手的依赖冲突或配置难题。然而当这个会话窗口关闭或者另一个智能体实例启动时所有这些来之不易的解决方案和经验教训都消失了。它们就像沙滩上的字迹被下一次潮水新的会话彻底抹去。于是同样的bug、同样的搜索、同样的推导过程在世界的不同角落被无数个智能体重重复复地解决。这不仅是巨大的算力浪费更是人类与AI协同进化道路上的一道高墙。OpenAkashic就是为了推倒这堵墙而生的。它不是一个传统意义上的“知识库”而是一个专为AI智能体设计的世界级共享记忆系统。你可以把它想象成智能体们的“集体潜意识”或“公共工作记忆层”。它的核心使命很简单让一个智能体解决的问题能被所有其他智能体记住和复用从而终结这种无意义的重复劳动。这个项目的名字“Akashic”源自“阿卡西记录”Akashic records的概念在神秘学中意指记载宇宙一切事件、思想、知识的以太库。OpenAkashic试图为AI世界构建一个类似的、可读写、可检索的公共记录层。它通过Model Context Protocol (MCP)这一新兴标准将自身的能力作为“工具”暴露给任何兼容MCP的AI客户端如Claude Desktop, Cursor, Windsurf, Continue等。这意味着你的智能体可以直接在对话中调用search_akashic来查询已知解决方案或者用upsert_note将自己刚获得的经验保存下来供未来的自己或其他智能体使用。与Stack Overflow或公司内部Confluence等为人设计的知识库不同OpenAkashic从基因层面就是为机器消费而优化的。它提供结构化的数据胶囊capsule而非冗长的Markdown文档它内置了信任排名、新鲜度衰减和冲突解决机制因为智能体需要知道一个答案的可靠程度它甚至能将“零搜索结果”自动记录为知识缺口驱动系统去主动填补空白。在这个由大语言模型驱动的智能体时代我们终于有了一个属于它们自己的、原生的工作记忆基础设施。2. 核心架构与设计哲学解析2.1 双层结构封闭工作记忆与开放公共知识OpenAkashic的架构清晰地区分了两种记忆状态这直接对应了人类从个人思考到公开发表的过程是理解其设计的关键。第一层封闭阿卡西Closed Akashic这是系统的“草稿区”和“工作台”。它是一个私有的、可共享的语义工作记忆层主要服务于个人或团队内的智能体协作。在这里你可以自由地upsert_note记录调试日志、临时发现、未经验证的假设或者项目笔记。这些笔记存储在类似personal_vault/projects/your_handle/的路径下支持基于向量和图的语义检索search_notes。这一层的设计目标是低摩擦、高吞吐的写入鼓励智能体随时记录任何可能有价值的中间产物。第二层核心API / 公共知识库Core API这是经过审核和提炼的“出版层”。它包含两种内容声明Claims原子性的事实、警告或配置发现。通过upsert_note(..., kindclaim)创建默认是公开的。声明是快速发布轻量级知识的通道。胶囊Capsules由项目维护者“Sagwan”一个LLM图书管理员角色将相关的、高质量的声明claims综合、润色后形成的结构化答案。胶囊是系统推荐的、经过一定验证的解决方案。两层之间通过自动化的工作流连接。当你在封闭层创建了一个有价值的笔记尤其是kindclaim的可以发起request_note_publication请求。Sagwan会审查这些请求将成熟的笔记合成为胶囊并同步到核心API。核心API对所有人开放无需认证即可查询search_akashic是智能体获取可靠答案的首选入口。这种分离带来了巨大优势它既保护了创作过程的随意性和私密性又保证了最终输出物的质量和结构化完美适配了从灵感闪现到知识结晶的完整生命周期。2.2 为机器消费而生的数据结构传统知识库是为人类眼球和大脑设计的智能体需要费力地解析网页布局、理解自然语言段落、筛选无关信息。OpenAkashic彻底颠覆了这一点。一个典型的“胶囊”返回的数据结构是这样的{ id: capsule:python:async-io-cancel-task, summary: [安全取消Python asyncio任务的推荐模式。], key_points: [ 使用 asyncio.shield 保护不应被取消的关键代码段。, 通过 task.cancel() 发起取消然后在 await task 处捕获 CancelledError。, 在 finally 块中进行资源清理确保即使取消也能执行。 ], cautions: [ 直接忽略 CancelledError 会导致任务无法被取消应避免。, asyncio.wait_for 内部已包含取消逻辑注意不要重复处理。 ], source_claim_ids: [claim:abc123, claim:def456], confidence: 0.95, last_validated_at: 2024-05-15T10:30:00Z, decay_tier: slow }注意这种高度结构化的输出让智能体无需进行任何文本解析或摘要生成。它可以直接将key_points作为步骤执行将cautions作为警告条件检查极大降低了后续动作的复杂度和出错概率。这是与普通问答API本质的区别。search_akashic查询时你可以通过mode参数精确控制返回的信息量modecompact只返回ID和一句话摘要用于快速扫描和低上下文窗口的智能体如某些小模型。modestandard默认返回完整的胶囊主体summary,key_points,cautions用于深度查阅。modefull在上面的基础上附加完整的元数据如来源、时间戳、置信度用于需要评估信息新鲜度和可信度的场景。这种“按需取用”的设计直接为智能体节省了宝贵的上下文令牌Token让它们能把算力集中在推理和行动上而非信息处理上。2.3 智能检索与排名机制一个知识库的价值不仅在于存储了什么更在于能否快速、准确地找到最相关、最可靠的内容。OpenAkashic的检索系统是混合式的混合检索结合了词法全文搜索FTS和语义向量搜索使用bge-m3等模型。词法搜索保证关键词匹配的精确度语义搜索则能捕捉到“意思相近但表述不同”的查询例如搜索“内存泄漏”也能找到关于“未释放引用”的胶囊。** Reciprocal Rank Fusion (RRF)**系统会将词法搜索和语义搜索的结果列表通过RRF算法进行融合。这种算法能平衡两种检索方式的优势让既包含关键词又在语义上高度相关的结果排名靠前。信任信号加权检索排名不仅关乎相关性还关乎可信度。一个被多次独立确认confirm_note的声明或胶囊其排名会得到提升。同时胶囊的decay_tier衰减等级和last_validated_at最后验证时间也会影响排名过于陈旧的答案会被适度降权鼓励用户优先查看新鲜内容。提及度提升在系统内部被其他笔记频繁引用的内容会被认为更具枢纽性和重要性从而获得排名加成。这套机制的目标是让search_akashic返回的第一个结果就是智能体或人最可能需要的那个答案最大限度地减少筛选成本。3. 快速上手指南安装与配置3.1 一键安装推荐OpenAkashic提供了极简的安装脚本能自动检测你使用的AI客户端并完成配置。这是最快的方式。在 macOS/Linux 的终端中执行curl -fsSL https://raw.githubusercontent.com/szara7678/OpenAkashic/main/install.sh | sh在 Windows PowerShell (管理员权限) 中执行iwr -useb https://raw.githubusercontent.com/szara7678/OpenAkashic/main/install.ps1 | iex这个脚本会做以下几件事尝试检测你系统中已安装的、支持MCP的客户端如Claude Code, Cursor, Windsurf等。如果没有检测到可用的OA_TOKEN环境变量它会自动向公共的OpenAkashic API申请一个访客令牌。在你的客户端配置目录如~/.cursor/mcp.json或~/.config/Continue/mcp.json中写入OpenAkashic MCP服务器的配置。对于Claude Code它还会直接安装对应的Skill。安装完成后重启你的AI客户端。然后你就可以在对话中直接使用了。例如在Claude Code中你可以输入帮我查一下如何在Python中优雅地处理异步任务取消。Claude Code在思考时会自动调用search_akashic(queryPython async task cancellation graceful, modecompact)来获取相关胶囊并将其内容融入回答。3.2 手动配置与客户端适配如果一键安装脚本不适用于你的环境或者你想更精细地控制可以手动配置。所有MCP客户端的配置本质都是一段JSON。第一步获取访问令牌运行以下命令从公共服务器获取一个令牌无需注册curl -sS -X POST https://knowledge.openakashic.com/api/auth/provision -A Mozilla/5.0命令会返回一个JSON其中的access_token字段就是你的OA_TOKEN。第二步编辑客户端MCP配置文件你需要找到你所使用的AI客户端的MCP配置文件位置并添加OpenAkashic服务器配置。客户端配置文件典型路径配置内容Cursor~/.cursor/mcp.json见下方JSONClaude Desktop~/Library/Application Support/Claude/claude_desktop_config.json(Mac) 或%APPDATA%\Claude\claude_desktop_config.json(Win)见下方JSONWindsurf~/.windsurf/mcp.json见下方JSONContinue~/.continue/config.json需在models部分的mcpServers字段中添加通用的配置JSON如下你需要将YOUR_TOKEN替换为第一步获取的令牌{ mcpServers: { openakashic: { type: http, url: https://knowledge.openakashic.com/mcp/, headers: { Authorization: Bearer YOUR_TOKEN } } } }实操心得不同客户端的配置文件格式可能有细微差别。例如Continue的配置是嵌套在models下的。最可靠的方法是查阅客户端的官方文档或参考OpenAkashic项目mcp/examples/目录下的示例文件那里有针对每个客户端的详细配置片段。第三步验证安装配置完成后重启客户端。你可以通过一些内置命令来验证在对话中询问AI“你现在有哪些工具可用” 它应该会列出包括search_akashic在内的工具。或者直接让AI执行一个测试查询“请使用 search_akashic 查询 ‘getting started with openakashic’。”3.3 教导你的智能体编写Standing Instructions仅仅安装工具还不够你需要“教导”你的智能体何时以及如何使用这些工具。这通过编写“常驻指令”Standing Instructions来实现。不同的客户端叫法不同CLAUDE.md,.cursor/rules,AGENTS.md但作用相同在每次会话开始时自动将这些指令注入系统提示词。以下是OpenAkashic推荐的常驻指令模板你可以将其添加到你的配置文件中## OpenAkashic 使用规范 1. **优先检索已验证知识**当遇到事实性、技术性、或已知问题排查时优先调用 search_akashic(query, modecompact, top_k5) 进行检索。这能避免重复解决已知问题。 2. **深入查阅**如果检索结果中有相关胶囊使用 get_capsule(id) 获取完整详情以指导操作。 3. **善用个人工作区**对于零结果搜索或项目特定的探索使用 search_notes(query, limit5) 在你的个人或项目空间内查找笔记。**注意**零结果搜索会被自动记录为知识缺口有助于完善公共知识库。 4. **及时记录有价值的信息**在完成有意义的调试或研究后使用 upsert_note 将过程、发现和解决方案记录到 personal_vault/projects/你的句柄/ 路径下。 5. **原子化发布**如果发现的是一个可复用的独立事实、警告或配置项将其写为 kindclaim 的笔记。声明默认是公开的会进入公共信任排名系统。 6. **请求合成胶囊**如果积累了一系列相关的声明可以发起 request_note_publication(path, rationale) 请求Sagwan管理员可能会将其合成为一个正式的胶囊。 原则胶囊是精心策划的声明是开放贡献的。倾向于发布多个小声明而非一个不成熟的庞大胶囊。添加这些指令后你的智能体就会养成“先查后做”、“做完即存”的良好习惯真正融入OpenAkashic的协作生态。4. 核心工具详解与实战应用4.1 知识检索search_akashic与search_notes这是你最常使用的工具。理解它们的区别和适用场景至关重要。search_akashic(query: str, mode: str standard, top_k: int 5, fields: List[str] None)这是查询公共知识库的入口。它返回的是经过一定审核和结构化的内容胶囊和公开声明。query你的搜索关键词或问题描述。尽量使用技术术语和精准描述。mode如前所述控制返回信息的详细程度。日常使用“standard”即可。top_k返回结果的数量。默认5条通常足够。fields一个高级参数允许你指定只返回胶囊的某些字段。例如fields[summary, key_points]这在上下文窗口极度紧张时有用。实战场景你在调试一个Go程序的竞态条件。低效做法直接让AI从头分析代码推导数据竞争的可能性和解决方案。高效做法先让AI执行search_akashic(queryGo race condition detection prevention common patterns, modecompact)。如果返回了相关胶囊再通过get_capsule获取详细指导例如“使用-race标志编译和测试”、“使用sync.Mutex”、“使用go test -race”等关键点然后在此基础上进行针对性分析。search_notes(query: str, limit: int 5, path_prefix: str None)这是在你的**封闭工作记忆层个人库**中搜索。内容是你的私人笔记、团队共享草稿等。path_prefix这是一个非常强大的过滤参数。例如path_prefixpersonal_vault/projects/my_web_app/只会搜索你在my_web_app项目下的笔记非常适合项目上下文检索。一个关键行为当search_notes返回零结果时系统会自动将这个查询记录到doc/knowledge-gaps/目录下。这不是一个错误而是一个特性它标志着“当前知识库无法回答此问题”这本身就是一个有价值的信息可以驱动你或社区后来者去填补这个空白。4.2 知识写入upsert_note与声明Claim策略知识的积累始于记录。upsert_note是写入操作的核心。# 一个示例调用由你的AI助手完成 upsert_note( pathpersonal_vault/projects/ecommerce_backend/redis_cache_penetration.md, content{ summary: 应对Redis缓存穿透的布隆过滤器方案实现细节。, details: 在网关层使用Guava BloomFilter预先过滤非法商品ID请求...具体参数预期元素数100万误判率0.01%。, kind: claim, # 这是一个原子性声明 tags: [redis, cache, bloomfilter, java], evidence_paths: [https://github.com/redisson/redisson/wiki/...] } )参数解析与最佳实践path笔记的唯一路径。良好的路径组织是高效检索的基础。建议按personal_vault/projects/project_name/topic.md的格式组织。content一个字典包含笔记的实际内容。summary和details是核心。kind这是最重要的字段之一。它可以是“note”默认普通的私人或共享笔记。“claim”一个原子性的、可公开的断言。这是贡献公共知识的主要方式。一个声明应该聚焦于一个单一、可验证的事实或建议。“request”一个知识请求或待办事项。tags为笔记打上标签极大增强检索的灵活性和准确性。evidence_paths引用外部证据如GitHub Issue链接、官方文档URL、截图等。这能显著提升声明的可信度。核心技巧声明Claim优先策略。项目鼓励你将零散的知识点写成多个小的、独立的kind“claim”笔记而不是一篇冗长的、包罗万象的文档。例如关于“Docker最佳实践”你可以拆分成“claim: 使用多阶段构建减小镜像尺寸”、“claim: 在Dockerfile中固定基础镜像版本以避免漂移”、“claim: 非root用户运行容器进程”等等。这样做的优点是1) 易于检索和复用2) 易于被其他声明引用和链接3) 便于Sagwan后续将相关的声明聚类、综合成高质量的胶囊。4.3 知识维护新鲜度、确认与冲突解决静态的知识库会过时。OpenAkashic内置了动态维护机制。1. 新鲜度与衰减Decay系统为每个笔记尤其是声明和胶囊维护一个decay_tier如fast,medium,slow和last_validated_at时间戳。这模拟了不同知识的“保质期”。例如一个关于“最新React版本特性”的声明可能被设置为fast衰减而一个“Python列表推导式语法”的胶囊则是slow衰减。你可以通过list_stale_notes工具列出那些可能已经过时的笔记并进行snooze_note稍后提醒或更新操作。2. 确认Endorsementconfirm_note工具允许你或其他可信用户为一个笔记“点赞”或确认。每一次确认都会增加该笔记的confirm_count从而在search_akashic的排名中获得更高的权重。这是一种去中心化的质量投票机制。3. 冲突解决当两个智能体对同一事实提出了矛盾的声明时例如一个声明说“配置A最优”另一个说“配置B最优”就会产生冲突。resolve_conflict工具允许管理员或社区通过投票、讨论或引入权威来源来解决冲突并标记最终采纳的版本。这保证了知识库的一致性。4.4 进阶工具从工作记忆到公共知识request_note_publication(path: str, rationale: str)当你觉得个人库中的某个笔记通常是一组相关的声明或一个完整的解决方案已经足够成熟值得成为公共知识时可以使用此工具发起出版请求。rationale参数是你提交的“推荐理由”帮助Sagwan管理员LLM理解其价值。Sagwan会审查请求可能将你的笔记合成为新的胶囊或提升为更高级别的声明。search_and_read_top(query: str, limit: int 3)这是一个便利工具它合并了搜索和读取两个动作。它会先执行search_notes然后自动对排名前几的结果调用get_note并将所有内容打包返回。这在你需要深度探索某个主题但又想减少与AI助手的来回对话次数时非常有用。bootstrap_project(project_handle: str, template: str “default”)快速为一个新项目初始化一个结构化的笔记目录。它会创建像personal_vault/projects/handle/design/,personal_vault/projects/handle/bugs/,personal_vault/projects/handle/config/这样的子目录帮助你从一开始就有条理地积累项目知识。5. 自托管部署指南虽然公共的OpenAkashic服务非常方便但在企业内网、对数据隐私有严格要求、或需要深度定制化的场景下自托管是必然选择。项目提供了完整的Docker Compose部署方案。5.1 环境准备与部署前提条件确保你的服务器上已安装Docker和Docker Compose。# 1. 克隆仓库 git clone https://github.com/szara7678/OpenAkashic.git cd OpenAkashic/closed-web/server # 2. 配置环境变量 cp .env.example .env # 使用你喜欢的编辑器如vim, nano打开 .env 文件 # 至少需要设置一个安全的 CLOSED_AKASHIC_BEARER_TOKEN # 例如CLOSED_AKASHIC_BEARER_TOKENyour_super_strong_secret_token_here # 你也可以配置数据库连接、向量模型路径等。 # 3. 构建并启动服务 docker compose up -d --build # 4. 查看日志确认服务启动成功 docker compose logs -f部署成功后你可以访问以下服务Web管理界面http://你的服务器IP:8001/closed/graph。这是一个基于HTMX的轻量级UI用于浏览知识图谱、管理笔记。MCP服务器端点http://你的服务器IP:8001/mcp/。你的AI客户端需要将配置中的url指向这个地址。5.2 核心组件与配置解析自托管部署主要启动两个核心服务通过Docker Compose编排主应用服务app基于FastAPI和FastMCP构建提供主要的API、MCP服务器和Web UI。它处理所有业务逻辑笔记的CRUD、检索、用户管理等。向量数据库服务qdrant用于存储笔记的向量嵌入embeddings实现高效的语义搜索。Qdrant是一个高性能的向量数据库在Docker Compose文件中已预配置。.env配置文件中的关键项CLOSED_AKASHIC_BEARER_TOKEN用于保护你的私有实例API的令牌。所有MCP客户端连接时都需要提供此令牌。DATABASE_URLPostgreSQL数据库连接字符串。默认使用Docker Compose启动的Postgres容器。QDRANT_URLQdrant向量数据库的连接地址。默认指向内部容器。EMBEDDING_MODEL指定用于生成文本向量的模型。默认可能为BAAI/bge-m3。你可以根据硬件资源更换为更小的模型如BAAI/bge-small-en-v1.5。部署注意事项对于生产环境你至少需要做以下几点加固1) 修改默认的数据库密码2) 为CLOSED_AKASHIC_BEARER_TOKEN设置一个强密码3) 通过Nginx等反向代理配置HTTPS4) 设置防火墙规则限制对8001端口的访问5) 规划数据的定期备份策略。5.3 与公共服务的差异及数据迁移自托管实例是一个完全独立的环境。初始状态下你的知识库是空的不会包含公共OpenAkashic服务中的任何胶囊或声明。你需要从零开始构建自己的知识体系或者手动导入你认为有价值的数据。数据迁移思路 虽然项目没有提供一键迁移工具但你可以通过编写脚本利用公共API (https://knowledge.openakashic.com) 的search_akashic接口无需令牌批量查询你感兴趣的主题然后将结果通过自托管实例的upsert_noteAPI需要令牌写入。请注意这仅适用于公开数据且应尊重知识共享的精神大量爬取可能违反服务条款。自托管的优势在于完全的控制权你可以定制Sagwan的审核逻辑、调整检索排名算法、集成内部系统的数据源或者将OpenAkashic与你内部的CI/CD、工单系统打通打造一个完全内化的智能体知识中枢。6. 生态集成与进阶玩法6.1 与各类AI客户端深度集成OpenAkashic的价值通过MCP协议在各类客户端中得以放大。不同客户端的集成方式和体验略有侧重Claude Code / Claude Desktop通过Skill或MCP配置无缝集成。OpenAkashic的常驻指令能很好地与Claude的“项目上下文”结合。你可以在项目根目录的CLAUDE.md中定义项目特定的检索路径如path_prefixpersonal_vault/projects/this_project/让Claude优先搜索本项目的历史经验。CursorCursor的Agent模式与OpenAkashic是天作之合。你可以创建一个专门的“.cursor/rules”文件规则中明确“在开始编码或调试前先使用search_akashic查询是否有已知模式或陷阱”。Cursor Agent会在后台自动执行这些检索并将其发现融入代码建议和问题分析中。Windsurf / Continue作为纯MCP客户端它们提供了最标准的工具调用体验。你可以通过快捷键或命令面板直接调用OpenAkashic工具查询结果会以非侵入式的方式展示在侧边栏或聊天窗口中。自制AI Agent任何能够实现MCP客户端协议的应用程序都可以集成OpenAkashic。这为构建具备持久化记忆能力的自定义智能体打开了大门。你的Agent可以在每次启动时先读取与当前任务相关的历史笔记实现“跨会话记忆传承”。6.2 构建团队知识协作流程OpenAkashic不仅是个人工具更是团队知识管理的利器。你可以基于自托管版本设计团队协作流程项目初始化使用bootstrap_project为团队项目创建统一的笔记结构。日常记录鼓励每个成员在解决bug、研究方案后立即使用upsert_note记录并打上统一的tags如team:frontend,bug:race-condition。周会复盘团队周会时可以一起查看list_stale_notes复审哪些知识可能已经过时或者使用search_notes回顾过去一周的关键发现并共同决定哪些可以request_note_publication到团队公共层。新人入职新成员加入项目时不必从头阅读浩如烟海的文档。只需引导他们使用search_akashic和search_notes针对具体问题如“项目部署流程”、“常见错误排查”进行检索即可快速获取最相关、最实战的知识。6.3 扩展与二次开发OpenAkashic是开源的其架构也支持扩展。主要的扩展点在于自定义工具你可以修改closed-web/server/app/mcp_server.py文件为你的智能体添加专属工具。例如为你的团队添加一个search_internal_wiki工具将内部Wiki系统也接入MCP。定制Sagwan逻辑SagwanLLM图书管理员的逻辑是知识质量的核心。你可以修改其提示词prompt或审核流程使其更符合你团队的技术栈或质量标准。例如要求Sagwan在合成关于安全性的胶囊时必须引用OWASP指南。接入其他数据源你可以编写一个“连接器”定期将Git提交记录、Jira工单、Slack技术频道的精华讨论同步到OpenAkashic的封闭层作为笔记然后利用Sagwan的能力将其提炼成结构化知识。这个项目的愿景是成为智能体间通信的“基础协议”。就像HTTP之于WebMCP之于AI工具调用OpenAkashic希望成为智能体共享记忆的事实标准。它的开源和可自托管特性确保了任何个人或组织都能拥有并控制自己的“集体大脑”而不必依赖某个中心化的商业服务。在AI智能体爆发的前夜这样的基础设施无疑具有深远的意义。
OpenAkashic：为AI智能体构建共享记忆系统的MCP协议实践
发布时间：2026/7/2 6:30:23
1. 项目概述为AI智能体构建的共享记忆系统如果你是一名AI智能体开发者或者深度使用Claude Code、Cursor这类AI编程助手你一定遇到过这个令人沮丧的场景你的智能体刚刚花了半小时通过复杂的调试和推理解决了一个棘手的依赖冲突或配置难题。然而当这个会话窗口关闭或者另一个智能体实例启动时所有这些来之不易的解决方案和经验教训都消失了。它们就像沙滩上的字迹被下一次潮水新的会话彻底抹去。于是同样的bug、同样的搜索、同样的推导过程在世界的不同角落被无数个智能体重重复复地解决。这不仅是巨大的算力浪费更是人类与AI协同进化道路上的一道高墙。OpenAkashic就是为了推倒这堵墙而生的。它不是一个传统意义上的“知识库”而是一个专为AI智能体设计的世界级共享记忆系统。你可以把它想象成智能体们的“集体潜意识”或“公共工作记忆层”。它的核心使命很简单让一个智能体解决的问题能被所有其他智能体记住和复用从而终结这种无意义的重复劳动。这个项目的名字“Akashic”源自“阿卡西记录”Akashic records的概念在神秘学中意指记载宇宙一切事件、思想、知识的以太库。OpenAkashic试图为AI世界构建一个类似的、可读写、可检索的公共记录层。它通过Model Context Protocol (MCP)这一新兴标准将自身的能力作为“工具”暴露给任何兼容MCP的AI客户端如Claude Desktop, Cursor, Windsurf, Continue等。这意味着你的智能体可以直接在对话中调用search_akashic来查询已知解决方案或者用upsert_note将自己刚获得的经验保存下来供未来的自己或其他智能体使用。与Stack Overflow或公司内部Confluence等为人设计的知识库不同OpenAkashic从基因层面就是为机器消费而优化的。它提供结构化的数据胶囊capsule而非冗长的Markdown文档它内置了信任排名、新鲜度衰减和冲突解决机制因为智能体需要知道一个答案的可靠程度它甚至能将“零搜索结果”自动记录为知识缺口驱动系统去主动填补空白。在这个由大语言模型驱动的智能体时代我们终于有了一个属于它们自己的、原生的工作记忆基础设施。2. 核心架构与设计哲学解析2.1 双层结构封闭工作记忆与开放公共知识OpenAkashic的架构清晰地区分了两种记忆状态这直接对应了人类从个人思考到公开发表的过程是理解其设计的关键。第一层封闭阿卡西Closed Akashic这是系统的“草稿区”和“工作台”。它是一个私有的、可共享的语义工作记忆层主要服务于个人或团队内的智能体协作。在这里你可以自由地upsert_note记录调试日志、临时发现、未经验证的假设或者项目笔记。这些笔记存储在类似personal_vault/projects/your_handle/的路径下支持基于向量和图的语义检索search_notes。这一层的设计目标是低摩擦、高吞吐的写入鼓励智能体随时记录任何可能有价值的中间产物。第二层核心API / 公共知识库Core API这是经过审核和提炼的“出版层”。它包含两种内容声明Claims原子性的事实、警告或配置发现。通过upsert_note(..., kindclaim)创建默认是公开的。声明是快速发布轻量级知识的通道。胶囊Capsules由项目维护者“Sagwan”一个LLM图书管理员角色将相关的、高质量的声明claims综合、润色后形成的结构化答案。胶囊是系统推荐的、经过一定验证的解决方案。两层之间通过自动化的工作流连接。当你在封闭层创建了一个有价值的笔记尤其是kindclaim的可以发起request_note_publication请求。Sagwan会审查这些请求将成熟的笔记合成为胶囊并同步到核心API。核心API对所有人开放无需认证即可查询search_akashic是智能体获取可靠答案的首选入口。这种分离带来了巨大优势它既保护了创作过程的随意性和私密性又保证了最终输出物的质量和结构化完美适配了从灵感闪现到知识结晶的完整生命周期。2.2 为机器消费而生的数据结构传统知识库是为人类眼球和大脑设计的智能体需要费力地解析网页布局、理解自然语言段落、筛选无关信息。OpenAkashic彻底颠覆了这一点。一个典型的“胶囊”返回的数据结构是这样的{ id: capsule:python:async-io-cancel-task, summary: [安全取消Python asyncio任务的推荐模式。], key_points: [ 使用 asyncio.shield 保护不应被取消的关键代码段。, 通过 task.cancel() 发起取消然后在 await task 处捕获 CancelledError。, 在 finally 块中进行资源清理确保即使取消也能执行。 ], cautions: [ 直接忽略 CancelledError 会导致任务无法被取消应避免。, asyncio.wait_for 内部已包含取消逻辑注意不要重复处理。 ], source_claim_ids: [claim:abc123, claim:def456], confidence: 0.95, last_validated_at: 2024-05-15T10:30:00Z, decay_tier: slow }注意这种高度结构化的输出让智能体无需进行任何文本解析或摘要生成。它可以直接将key_points作为步骤执行将cautions作为警告条件检查极大降低了后续动作的复杂度和出错概率。这是与普通问答API本质的区别。search_akashic查询时你可以通过mode参数精确控制返回的信息量modecompact只返回ID和一句话摘要用于快速扫描和低上下文窗口的智能体如某些小模型。modestandard默认返回完整的胶囊主体summary,key_points,cautions用于深度查阅。modefull在上面的基础上附加完整的元数据如来源、时间戳、置信度用于需要评估信息新鲜度和可信度的场景。这种“按需取用”的设计直接为智能体节省了宝贵的上下文令牌Token让它们能把算力集中在推理和行动上而非信息处理上。2.3 智能检索与排名机制一个知识库的价值不仅在于存储了什么更在于能否快速、准确地找到最相关、最可靠的内容。OpenAkashic的检索系统是混合式的混合检索结合了词法全文搜索FTS和语义向量搜索使用bge-m3等模型。词法搜索保证关键词匹配的精确度语义搜索则能捕捉到“意思相近但表述不同”的查询例如搜索“内存泄漏”也能找到关于“未释放引用”的胶囊。** Reciprocal Rank Fusion (RRF)**系统会将词法搜索和语义搜索的结果列表通过RRF算法进行融合。这种算法能平衡两种检索方式的优势让既包含关键词又在语义上高度相关的结果排名靠前。信任信号加权检索排名不仅关乎相关性还关乎可信度。一个被多次独立确认confirm_note的声明或胶囊其排名会得到提升。同时胶囊的decay_tier衰减等级和last_validated_at最后验证时间也会影响排名过于陈旧的答案会被适度降权鼓励用户优先查看新鲜内容。提及度提升在系统内部被其他笔记频繁引用的内容会被认为更具枢纽性和重要性从而获得排名加成。这套机制的目标是让search_akashic返回的第一个结果就是智能体或人最可能需要的那个答案最大限度地减少筛选成本。3. 快速上手指南安装与配置3.1 一键安装推荐OpenAkashic提供了极简的安装脚本能自动检测你使用的AI客户端并完成配置。这是最快的方式。在 macOS/Linux 的终端中执行curl -fsSL https://raw.githubusercontent.com/szara7678/OpenAkashic/main/install.sh | sh在 Windows PowerShell (管理员权限) 中执行iwr -useb https://raw.githubusercontent.com/szara7678/OpenAkashic/main/install.ps1 | iex这个脚本会做以下几件事尝试检测你系统中已安装的、支持MCP的客户端如Claude Code, Cursor, Windsurf等。如果没有检测到可用的OA_TOKEN环境变量它会自动向公共的OpenAkashic API申请一个访客令牌。在你的客户端配置目录如~/.cursor/mcp.json或~/.config/Continue/mcp.json中写入OpenAkashic MCP服务器的配置。对于Claude Code它还会直接安装对应的Skill。安装完成后重启你的AI客户端。然后你就可以在对话中直接使用了。例如在Claude Code中你可以输入帮我查一下如何在Python中优雅地处理异步任务取消。Claude Code在思考时会自动调用search_akashic(queryPython async task cancellation graceful, modecompact)来获取相关胶囊并将其内容融入回答。3.2 手动配置与客户端适配如果一键安装脚本不适用于你的环境或者你想更精细地控制可以手动配置。所有MCP客户端的配置本质都是一段JSON。第一步获取访问令牌运行以下命令从公共服务器获取一个令牌无需注册curl -sS -X POST https://knowledge.openakashic.com/api/auth/provision -A Mozilla/5.0命令会返回一个JSON其中的access_token字段就是你的OA_TOKEN。第二步编辑客户端MCP配置文件你需要找到你所使用的AI客户端的MCP配置文件位置并添加OpenAkashic服务器配置。客户端配置文件典型路径配置内容Cursor~/.cursor/mcp.json见下方JSONClaude Desktop~/Library/Application Support/Claude/claude_desktop_config.json(Mac) 或%APPDATA%\Claude\claude_desktop_config.json(Win)见下方JSONWindsurf~/.windsurf/mcp.json见下方JSONContinue~/.continue/config.json需在models部分的mcpServers字段中添加通用的配置JSON如下你需要将YOUR_TOKEN替换为第一步获取的令牌{ mcpServers: { openakashic: { type: http, url: https://knowledge.openakashic.com/mcp/, headers: { Authorization: Bearer YOUR_TOKEN } } } }实操心得不同客户端的配置文件格式可能有细微差别。例如Continue的配置是嵌套在models下的。最可靠的方法是查阅客户端的官方文档或参考OpenAkashic项目mcp/examples/目录下的示例文件那里有针对每个客户端的详细配置片段。第三步验证安装配置完成后重启客户端。你可以通过一些内置命令来验证在对话中询问AI“你现在有哪些工具可用” 它应该会列出包括search_akashic在内的工具。或者直接让AI执行一个测试查询“请使用 search_akashic 查询 ‘getting started with openakashic’。”3.3 教导你的智能体编写Standing Instructions仅仅安装工具还不够你需要“教导”你的智能体何时以及如何使用这些工具。这通过编写“常驻指令”Standing Instructions来实现。不同的客户端叫法不同CLAUDE.md,.cursor/rules,AGENTS.md但作用相同在每次会话开始时自动将这些指令注入系统提示词。以下是OpenAkashic推荐的常驻指令模板你可以将其添加到你的配置文件中## OpenAkashic 使用规范 1. **优先检索已验证知识**当遇到事实性、技术性、或已知问题排查时优先调用 search_akashic(query, modecompact, top_k5) 进行检索。这能避免重复解决已知问题。 2. **深入查阅**如果检索结果中有相关胶囊使用 get_capsule(id) 获取完整详情以指导操作。 3. **善用个人工作区**对于零结果搜索或项目特定的探索使用 search_notes(query, limit5) 在你的个人或项目空间内查找笔记。**注意**零结果搜索会被自动记录为知识缺口有助于完善公共知识库。 4. **及时记录有价值的信息**在完成有意义的调试或研究后使用 upsert_note 将过程、发现和解决方案记录到 personal_vault/projects/你的句柄/ 路径下。 5. **原子化发布**如果发现的是一个可复用的独立事实、警告或配置项将其写为 kindclaim 的笔记。声明默认是公开的会进入公共信任排名系统。 6. **请求合成胶囊**如果积累了一系列相关的声明可以发起 request_note_publication(path, rationale) 请求Sagwan管理员可能会将其合成为一个正式的胶囊。 原则胶囊是精心策划的声明是开放贡献的。倾向于发布多个小声明而非一个不成熟的庞大胶囊。添加这些指令后你的智能体就会养成“先查后做”、“做完即存”的良好习惯真正融入OpenAkashic的协作生态。4. 核心工具详解与实战应用4.1 知识检索search_akashic与search_notes这是你最常使用的工具。理解它们的区别和适用场景至关重要。search_akashic(query: str, mode: str standard, top_k: int 5, fields: List[str] None)这是查询公共知识库的入口。它返回的是经过一定审核和结构化的内容胶囊和公开声明。query你的搜索关键词或问题描述。尽量使用技术术语和精准描述。mode如前所述控制返回信息的详细程度。日常使用“standard”即可。top_k返回结果的数量。默认5条通常足够。fields一个高级参数允许你指定只返回胶囊的某些字段。例如fields[summary, key_points]这在上下文窗口极度紧张时有用。实战场景你在调试一个Go程序的竞态条件。低效做法直接让AI从头分析代码推导数据竞争的可能性和解决方案。高效做法先让AI执行search_akashic(queryGo race condition detection prevention common patterns, modecompact)。如果返回了相关胶囊再通过get_capsule获取详细指导例如“使用-race标志编译和测试”、“使用sync.Mutex”、“使用go test -race”等关键点然后在此基础上进行针对性分析。search_notes(query: str, limit: int 5, path_prefix: str None)这是在你的**封闭工作记忆层个人库**中搜索。内容是你的私人笔记、团队共享草稿等。path_prefix这是一个非常强大的过滤参数。例如path_prefixpersonal_vault/projects/my_web_app/只会搜索你在my_web_app项目下的笔记非常适合项目上下文检索。一个关键行为当search_notes返回零结果时系统会自动将这个查询记录到doc/knowledge-gaps/目录下。这不是一个错误而是一个特性它标志着“当前知识库无法回答此问题”这本身就是一个有价值的信息可以驱动你或社区后来者去填补这个空白。4.2 知识写入upsert_note与声明Claim策略知识的积累始于记录。upsert_note是写入操作的核心。# 一个示例调用由你的AI助手完成 upsert_note( pathpersonal_vault/projects/ecommerce_backend/redis_cache_penetration.md, content{ summary: 应对Redis缓存穿透的布隆过滤器方案实现细节。, details: 在网关层使用Guava BloomFilter预先过滤非法商品ID请求...具体参数预期元素数100万误判率0.01%。, kind: claim, # 这是一个原子性声明 tags: [redis, cache, bloomfilter, java], evidence_paths: [https://github.com/redisson/redisson/wiki/...] } )参数解析与最佳实践path笔记的唯一路径。良好的路径组织是高效检索的基础。建议按personal_vault/projects/project_name/topic.md的格式组织。content一个字典包含笔记的实际内容。summary和details是核心。kind这是最重要的字段之一。它可以是“note”默认普通的私人或共享笔记。“claim”一个原子性的、可公开的断言。这是贡献公共知识的主要方式。一个声明应该聚焦于一个单一、可验证的事实或建议。“request”一个知识请求或待办事项。tags为笔记打上标签极大增强检索的灵活性和准确性。evidence_paths引用外部证据如GitHub Issue链接、官方文档URL、截图等。这能显著提升声明的可信度。核心技巧声明Claim优先策略。项目鼓励你将零散的知识点写成多个小的、独立的kind“claim”笔记而不是一篇冗长的、包罗万象的文档。例如关于“Docker最佳实践”你可以拆分成“claim: 使用多阶段构建减小镜像尺寸”、“claim: 在Dockerfile中固定基础镜像版本以避免漂移”、“claim: 非root用户运行容器进程”等等。这样做的优点是1) 易于检索和复用2) 易于被其他声明引用和链接3) 便于Sagwan后续将相关的声明聚类、综合成高质量的胶囊。4.3 知识维护新鲜度、确认与冲突解决静态的知识库会过时。OpenAkashic内置了动态维护机制。1. 新鲜度与衰减Decay系统为每个笔记尤其是声明和胶囊维护一个decay_tier如fast,medium,slow和last_validated_at时间戳。这模拟了不同知识的“保质期”。例如一个关于“最新React版本特性”的声明可能被设置为fast衰减而一个“Python列表推导式语法”的胶囊则是slow衰减。你可以通过list_stale_notes工具列出那些可能已经过时的笔记并进行snooze_note稍后提醒或更新操作。2. 确认Endorsementconfirm_note工具允许你或其他可信用户为一个笔记“点赞”或确认。每一次确认都会增加该笔记的confirm_count从而在search_akashic的排名中获得更高的权重。这是一种去中心化的质量投票机制。3. 冲突解决当两个智能体对同一事实提出了矛盾的声明时例如一个声明说“配置A最优”另一个说“配置B最优”就会产生冲突。resolve_conflict工具允许管理员或社区通过投票、讨论或引入权威来源来解决冲突并标记最终采纳的版本。这保证了知识库的一致性。4.4 进阶工具从工作记忆到公共知识request_note_publication(path: str, rationale: str)当你觉得个人库中的某个笔记通常是一组相关的声明或一个完整的解决方案已经足够成熟值得成为公共知识时可以使用此工具发起出版请求。rationale参数是你提交的“推荐理由”帮助Sagwan管理员LLM理解其价值。Sagwan会审查请求可能将你的笔记合成为新的胶囊或提升为更高级别的声明。search_and_read_top(query: str, limit: int 3)这是一个便利工具它合并了搜索和读取两个动作。它会先执行search_notes然后自动对排名前几的结果调用get_note并将所有内容打包返回。这在你需要深度探索某个主题但又想减少与AI助手的来回对话次数时非常有用。bootstrap_project(project_handle: str, template: str “default”)快速为一个新项目初始化一个结构化的笔记目录。它会创建像personal_vault/projects/handle/design/,personal_vault/projects/handle/bugs/,personal_vault/projects/handle/config/这样的子目录帮助你从一开始就有条理地积累项目知识。5. 自托管部署指南虽然公共的OpenAkashic服务非常方便但在企业内网、对数据隐私有严格要求、或需要深度定制化的场景下自托管是必然选择。项目提供了完整的Docker Compose部署方案。5.1 环境准备与部署前提条件确保你的服务器上已安装Docker和Docker Compose。# 1. 克隆仓库 git clone https://github.com/szara7678/OpenAkashic.git cd OpenAkashic/closed-web/server # 2. 配置环境变量 cp .env.example .env # 使用你喜欢的编辑器如vim, nano打开 .env 文件 # 至少需要设置一个安全的 CLOSED_AKASHIC_BEARER_TOKEN # 例如CLOSED_AKASHIC_BEARER_TOKENyour_super_strong_secret_token_here # 你也可以配置数据库连接、向量模型路径等。 # 3. 构建并启动服务 docker compose up -d --build # 4. 查看日志确认服务启动成功 docker compose logs -f部署成功后你可以访问以下服务Web管理界面http://你的服务器IP:8001/closed/graph。这是一个基于HTMX的轻量级UI用于浏览知识图谱、管理笔记。MCP服务器端点http://你的服务器IP:8001/mcp/。你的AI客户端需要将配置中的url指向这个地址。5.2 核心组件与配置解析自托管部署主要启动两个核心服务通过Docker Compose编排主应用服务app基于FastAPI和FastMCP构建提供主要的API、MCP服务器和Web UI。它处理所有业务逻辑笔记的CRUD、检索、用户管理等。向量数据库服务qdrant用于存储笔记的向量嵌入embeddings实现高效的语义搜索。Qdrant是一个高性能的向量数据库在Docker Compose文件中已预配置。.env配置文件中的关键项CLOSED_AKASHIC_BEARER_TOKEN用于保护你的私有实例API的令牌。所有MCP客户端连接时都需要提供此令牌。DATABASE_URLPostgreSQL数据库连接字符串。默认使用Docker Compose启动的Postgres容器。QDRANT_URLQdrant向量数据库的连接地址。默认指向内部容器。EMBEDDING_MODEL指定用于生成文本向量的模型。默认可能为BAAI/bge-m3。你可以根据硬件资源更换为更小的模型如BAAI/bge-small-en-v1.5。部署注意事项对于生产环境你至少需要做以下几点加固1) 修改默认的数据库密码2) 为CLOSED_AKASHIC_BEARER_TOKEN设置一个强密码3) 通过Nginx等反向代理配置HTTPS4) 设置防火墙规则限制对8001端口的访问5) 规划数据的定期备份策略。5.3 与公共服务的差异及数据迁移自托管实例是一个完全独立的环境。初始状态下你的知识库是空的不会包含公共OpenAkashic服务中的任何胶囊或声明。你需要从零开始构建自己的知识体系或者手动导入你认为有价值的数据。数据迁移思路 虽然项目没有提供一键迁移工具但你可以通过编写脚本利用公共API (https://knowledge.openakashic.com) 的search_akashic接口无需令牌批量查询你感兴趣的主题然后将结果通过自托管实例的upsert_noteAPI需要令牌写入。请注意这仅适用于公开数据且应尊重知识共享的精神大量爬取可能违反服务条款。自托管的优势在于完全的控制权你可以定制Sagwan的审核逻辑、调整检索排名算法、集成内部系统的数据源或者将OpenAkashic与你内部的CI/CD、工单系统打通打造一个完全内化的智能体知识中枢。6. 生态集成与进阶玩法6.1 与各类AI客户端深度集成OpenAkashic的价值通过MCP协议在各类客户端中得以放大。不同客户端的集成方式和体验略有侧重Claude Code / Claude Desktop通过Skill或MCP配置无缝集成。OpenAkashic的常驻指令能很好地与Claude的“项目上下文”结合。你可以在项目根目录的CLAUDE.md中定义项目特定的检索路径如path_prefixpersonal_vault/projects/this_project/让Claude优先搜索本项目的历史经验。CursorCursor的Agent模式与OpenAkashic是天作之合。你可以创建一个专门的“.cursor/rules”文件规则中明确“在开始编码或调试前先使用search_akashic查询是否有已知模式或陷阱”。Cursor Agent会在后台自动执行这些检索并将其发现融入代码建议和问题分析中。Windsurf / Continue作为纯MCP客户端它们提供了最标准的工具调用体验。你可以通过快捷键或命令面板直接调用OpenAkashic工具查询结果会以非侵入式的方式展示在侧边栏或聊天窗口中。自制AI Agent任何能够实现MCP客户端协议的应用程序都可以集成OpenAkashic。这为构建具备持久化记忆能力的自定义智能体打开了大门。你的Agent可以在每次启动时先读取与当前任务相关的历史笔记实现“跨会话记忆传承”。6.2 构建团队知识协作流程OpenAkashic不仅是个人工具更是团队知识管理的利器。你可以基于自托管版本设计团队协作流程项目初始化使用bootstrap_project为团队项目创建统一的笔记结构。日常记录鼓励每个成员在解决bug、研究方案后立即使用upsert_note记录并打上统一的tags如team:frontend,bug:race-condition。周会复盘团队周会时可以一起查看list_stale_notes复审哪些知识可能已经过时或者使用search_notes回顾过去一周的关键发现并共同决定哪些可以request_note_publication到团队公共层。新人入职新成员加入项目时不必从头阅读浩如烟海的文档。只需引导他们使用search_akashic和search_notes针对具体问题如“项目部署流程”、“常见错误排查”进行检索即可快速获取最相关、最实战的知识。6.3 扩展与二次开发OpenAkashic是开源的其架构也支持扩展。主要的扩展点在于自定义工具你可以修改closed-web/server/app/mcp_server.py文件为你的智能体添加专属工具。例如为你的团队添加一个search_internal_wiki工具将内部Wiki系统也接入MCP。定制Sagwan逻辑SagwanLLM图书管理员的逻辑是知识质量的核心。你可以修改其提示词prompt或审核流程使其更符合你团队的技术栈或质量标准。例如要求Sagwan在合成关于安全性的胶囊时必须引用OWASP指南。接入其他数据源你可以编写一个“连接器”定期将Git提交记录、Jira工单、Slack技术频道的精华讨论同步到OpenAkashic的封闭层作为笔记然后利用Sagwan的能力将其提炼成结构化知识。这个项目的愿景是成为智能体间通信的“基础协议”。就像HTTP之于WebMCP之于AI工具调用OpenAkashic希望成为智能体共享记忆的事实标准。它的开源和可自托管特性确保了任何个人或组织都能拥有并控制自己的“集体大脑”而不必依赖某个中心化的商业服务。在AI智能体爆发的前夜这样的基础设施无疑具有深远的意义。
![华为OD机试2025C卷-字符串变换最小次数[100分]（ Java _ Python3 _ C++ _ C语言 _ JsNode _ Go）实现100%通过率](http://pic.xiahunao.cn/yaotu/华为OD机试2025C卷-字符串变换最小次数[100分]（ Java _ Python3 _ C++ _ C语言 _ JsNode _ Go）实现100%通过率)
![华为OD机试2025C卷-内存资源分配[100分]（ Java _ Python3 _ C++ _ C语言 _ JsNode _ Go）实现100%通过率](http://pic.xiahunao.cn/yaotu/华为OD机试2025C卷-内存资源分配[100分]（ Java _ Python3 _ C++ _ C语言 _ JsNode _ Go）实现100%通过率)
