EverOS：为AI应用构建本地优先的统一记忆层

1. 先搞清楚 EverOS 到底解决什么实际问题如果你在构建 AI 应用时遇到过这些问题EverOS 就值得一看不同 AI 助手之间记忆不互通每次对话都要重新交代背景长期项目的信息散落在聊天记录、笔记、代码注释里找不到统一入口想给 AI 助手添加持久记忆但不想依赖云服务或复杂数据库希望记忆数据完全可控能本地存储、版本管理、直接编辑EverOS 的核心价值就一句话为 AI 应用提供统一的本地优先记忆层。它不是另一个聊天机器人而是一个底层基础设施——把对话、文件、任务轨迹都转换成可读的 Markdown再用 SQLite 和 LanceDB 建立索引让任何 AI 工具都能共享同一套记忆系统。最特别的是它的“三层架构”Markdown 作为人类可读的原始记录SQLite 处理关系型查询LanceDB 负责向量检索。这种设计让记忆既能被 Git 版本管理又能支持语义搜索还不需要 MongoDB、Elasticsearch 这类重型依赖。2. 本地运行需要准备什么环境2.1 基础环境要求EverOS 是 Python 库但对版本有硬性要求# 确认 Python 版本 python --version # 必须 3.12 # 如果版本不够用 pyenv 或 conda 管理 pyenv install 3.12.0 pyenv global 3.12.0我建议先用虚拟环境隔离依赖避免污染系统 Python# 用 uv推荐或 venv 创建虚拟环境 uv venv everos-demo source everos-demo/bin/activate # Linux/macOS # everos-demo\Scripts\activate # Windows # 或者直接用 uv 管理 uv init everos-demo cd everos-demo2.2 API 密钥配置策略EverOS 的设计很务实演示模式不需要任何密钥完整功能才需要配置。如果你只是想先看看效果直接跳到下一节跑 demo 就行。真正要处理实际任务时需要两个服务商的密钥能力服务商用途环境变量名聊天多模态OpenRouterLLM 推理EVEROS_LLM__API_KEY嵌入重排序DeepInfra向量处理EVEROS_EMBEDDING__API_KEY为什么选这两个组合OpenRouter 聚合了多个主流模型DeepInfra 的嵌入服务性价比高。但 EverOS 其实兼容任何 OpenAI 协议的端点你完全可以用本地部署的 Ollama 或 vLLM 替代。配置时注意密钥的存放位置优先级命令行指定--env-file路径当前目录的.env文件~/.config/everos/.envXDG 标准~/.everos/.env传统位置3. 从演示模式到真实服务的过渡路径3.1 第一步不依赖外部服务的纯演示刚开始接触时不要急着配密钥。先运行教育性质的演示模式# 安装基础包 uv pip install everos # 启动交互式演示 everos demo这个演示会问你一个问题比如你最喜欢的爱好是什么然后展示完整的记忆生命周期对话输入 → 记忆球生成 → 检索召回 → 溯源证明 → 成功动画。按r重播按q退出。演示模式完全本地运行不连接任何外部服务适合理解核心概念。如果你在无界面的服务器环境或者想要可复现的文本输出用everos demo --plain # 纯文本模式 everos demo --cinematic # 循环展示模式适合录屏3.2 第二步配置真实服务环境确认演示模式能跑通后再配置真实服务# 生成配置文件模板 everos init # 编辑生成的 .env 文件填入密钥 vim .env # 或你喜欢的编辑器生成的.env文件会有详细注释你只需要填四个字段# LLM 推理OpenRouter EVEROS_LLM__API_KEYyour_openrouter_key_here EVEROS_MULTIMODAL__API_KEYyour_openrouter_key_here # 向量处理DeepInfra EVEROS_EMBEDDING__API_KEYyour_deepinfra_key_here EVEROS_RERANK__API_KEYyour_deepinfra_key_here如果你想用其他兼容 OpenAI 的服务比如本地 Ollama修改对应的BASE_URLEVEROS_LLM__BASE_URLhttp://localhost:11434/v1 EVEROS_LLM__API_KEYollama # 本地部署通常不需要真密钥3.3 第三步启动服务并验证配置完成后启动记忆服务# 启动服务默认端口 8000 everos server start # 在另一个终端验证服务状态 curl http://127.0.0.1:8000/health看到{status:ok}说明服务正常。现在可以运行连接真实服务的演示everos demo --live # 连接本地服务 everos demo --live --server-url http://your-server:port # 连接远程服务--live模式会执行真实的 API 调用流程健康检查 → 添加记忆 → 刷新索引 → 语义搜索 → 可视化展示。这是从演示到实战的关键过渡。4. 实际使用时的核心操作流程4.1 添加第一条记忆记录服务运行后通过 REST API 添加记忆。EverOS 的 API 设计很直观主要围绕几个核心维度组织记忆# 添加对话记忆 curl -X POST http://127.0.0.1:8000/api/v1/memory/add \ -H Content-Type: application/json \ -d { session_id: project-planning-001, app_id: coding-assistant, project_id: web-app, messages: [ { sender_id: developer, role: user, timestamp: 1741968000000, content: 我们需要用 React 和 FastAPI 构建一个任务管理应用 }, { sender_id: ai-assistant, role: assistant, timestamp: 1741968100000, content: 建议使用 SQLite 作为本地数据库前端用 Ant Design 组件库 } ] }关键参数说明session_id: 对话会话标识同一会话的记忆会关联app_id: 应用类型如 coding-assistant、creative-helper 等project_id: 项目标识支持跨项目记忆检索sender_id: 发送者身份支持多用户场景4.2 触发记忆提取和索引添加记忆后需要显式触发处理流程# 刷新指定会话的记忆 curl -X POST http://127.0.0.1:8000/api/v1/memory/flush \ -H Content-Type: application/json \ -d { session_id: project-planning-001, app_id: coding-assistant, project_id: web-app }这个操作会提取对话中的关键实体和关系生成可读的 Markdown 文件源文件更新 SQLite 的关系索引更新 LanceDB 的向量索引重要提醒Markdown 文件是同步写入的但索引更新是后台任务。如果立即搜索可能找不到新记忆等几秒再试。4.3 检索记忆的多种方式检索是记忆系统的核心价值。EverOS 支持多种查询模式# 语义搜索最常用 curl -X POST http://127.0.0.1:8000/api/v1/memory/search \ -H Content-Type: application/json \ -d { user_id: developer, app_id: coding-assistant, project_id: web-app, query: 之前讨论过用什么前端框架, top_k: 3 } # 按时间范围筛选 curl -X POST http://127.0.0.1:8000/api/v1/memory/search \ -H Content-Type: application/json \ -d { user_id: developer, start_time: 1741968000000, end_time: 1741968200000, top_k: 10 }检索结果包含原始内容、相关性分数和溯源信息方便验证记忆准确性。5. 文件处理和多媒体支持5.1 安装多媒体扩展除了文本对话EverOS 还能处理各种文件格式# 安装多媒体支持扩展 uv pip install everos[multimodal]这个扩展包依赖everalgo-parser支持图像文件PNG、JPG、SVG 等PDF 文档音频文件MP3、WAV 等Office 文档需要系统依赖5.2 Office 文档的系统依赖处理 Word、Excel、PPT 文件需要 LibreOffice# macOS brew install --cask libreoffice # Ubuntu/Debian sudo apt-get install -y libreoffice # CentOS/RHEL sudo yum install -y libreoffice如果没有安装 LibreOffice上传 Office 文档时会返回明确的错误信息。PDF 和图像处理不受影响。5.3 文件上传示例上传文件到记忆系统# 准备文件上传假设有 test.pdf curl -X POST http://127.0.0.1:8000/api/v1/memory/add \ -H Content-Type: application/json \ -d { session_id: document-review-001, app_id: research-assistant, project_id: academic-paper, messages: [ { sender_id: researcher, role: user, timestamp: 1741968300000, content: [ { type: text, text: 请分析这份技术文档的核心观点 }, { type: file, file: { path: /path/to/test.pdf, mime_type: application/pdf } } ] } ] }文件内容会被解析并整合到记忆系统中后续可以通过语义搜索检索文档内容。6. 生产环境部署考量6.1 存储目录结构理解EverOS 采用清晰的目录结构管理记忆数据~/.everos/ ├── memories/ # Markdown 源文件 │ ├── user_alice/ │ │ ├── app_coding-assistant/ │ │ │ └── project_web-app.md │ │ └── app_creative-helper/ │ └── user_bob/ ├── indexes/ # 数据库索引 │ ├── sqlite/ │ │ └── everos.db │ └── lancedb/ │ └── vectors/ └── logs/ # 运行日志这种结构的好处源文件人类可读可以直接用 Git 管理版本索引与源文件分离重建索引不会丢失原始数据按用户、应用、项目分级权限管理清晰6.2 性能优化建议根据使用规模调整配置# config.toml 示例高级配置 [indexing] batch_size 100 # 索引批处理大小 vector_dimension 1536 # 向量维度适配不同模型 max_concurrent_tasks 4 # 并发任务数 [storage] auto_cleanup_days 30 # 自动清理旧索引 compress_old_files true # 压缩旧文件对于大规模部署考虑使用 SSD 提升索引速度调整batch_size平衡内存使用和吞吐量设置定期清理策略避免存储膨胀6.3 监控和排查要点服务运行后关注这些指标# 检查服务健康状态 curl http://127.0.0.1:8000/health # 查看存储使用情况 du -sh ~/.everos/ # 检查索引完整性 curl -X POST http://127.0.0.1:8000/api/v1/debug/stats常见问题排查顺序服务未启动检查端口占用和防火墙设置记忆添加失败验证 JSON 格式和必需字段搜索无结果确认 flush 操作已完成等待索引更新文件处理错误检查文件权限和系统依赖7. 与其他 AI 工具的集成模式7.1 与编程助手集成EverOS 最自然的应用场景是增强编程助手。比如为 Claude Code、Cursor 等工具添加持久记忆# 示例在 AI 编码工具中集成记忆功能 import requests class CodingAssistantWithMemory: def __init__(self, everos_base_urlhttp://localhost:8000): self.base_url everos_base_url def save_context(self, session_id, project_context, code_discussion): 保存编程会话上下文 memory_data { session_id: session_id, app_id: coding-assistant, project_id: current-project, messages: [ { sender_id: developer, role: user, timestamp: self._current_timestamp(), content: f项目背景{project_context} }, { sender_id: ai-assistant, role: assistant, timestamp: self._current_timestamp() 1000, content: f代码讨论{code_discussion} } ] } response requests.post( f{self.base_url}/api/v1/memory/add, jsonmemory_data ) return response.json() def recall_related_code(self, query, top_k5): 检索相关的代码讨论 search_data { user_id: developer, app_id: coding-assistant, query: query, top_k: top_k } response requests.post( f{self.base_url}/api/v1/memory/search, jsonsearch_data ) return response.json()7.2 多应用共享记忆真正的价值在于跨应用记忆共享。比如创意写作助手和代码助手可以访问同一项目的记忆# 创意助手检索编程相关的记忆 def get_technical_context_for_story(project_name, creative_query): 为创意写作获取技术背景 search_payload { app_id: coding-assistant, # 从编程助手记忆检索 project_id: project_name, query: f{creative_query} 技术实现, top_k: 3 } # 即使当前应用是 creative-assistant也能访问 coding-assistant 的记忆 response requests.post( http://localhost:8000/api/v1/memory/search, jsonsearch_payload ) return [item[content] for item in response.json()[results]]8. 实际使用中的经验要点8.1 记忆组织的最佳实践基于实际使用经验建议这样组织记忆结构按项目划分优于按时间划分不好的做法所有对话都放到default项目好的做法每个真实项目有独立的project_id用户身份清晰分离单人使用固定user_id如 primary-user团队使用区分user_id支持权限控制会话生命周期管理短期任务使用时间戳前缀如2025-03-project-planning长期项目使用稳定标识如web-app-development8.2 性能与稳定性权衡索引更新策略实时性要求高添加记忆后立即调用flush批量处理场景积累一批记忆后统一flush搜索精度调节精确匹配top_k3-5高相关性阈值探索性搜索top_k10-20发现潜在关联资源使用监控小规模使用默认配置足够大规模部署监控~/.everos目录大小定期归档旧项目8.3 故障恢复流程当遇到问题时按这个顺序排查检查服务状态curl http://localhost:8000/health ps aux | grep everos验证基础功能# 测试最简单的记忆流程 everos demo --live检查存储权限ls -la ~/.everos/ # 确认当前用户有读写权限查看详细日志tail -f ~/.everos/logs/everos.log重建索引最后手段# 停止服务后 rm -rf ~/.everos/indexes/ # 重新启动服务索引会自动重建EverOS 的强项在于数据持久化策略——即使索引损坏原始 Markdown 文件仍然完好重建索引不会丢失记忆。这个方案真正落地时最关键的不是功能有多丰富而是记忆检索的准确性和一致性。建议先用小规模项目验证工作流程再逐步扩展到生产环境。对于长期使用的场景要建立定期备份和监控机制确保记忆系统的可靠性。