EverOS 是 EverMind-AI 开源的一个本地优先的记忆运行时和 Python 库专为 AI 智能体和开发者设计。它提供了一个跨应用、跨设备的便携式记忆层让 AI 助手能够记住过去的对话、文件和处理轨迹并在后续交互中智能地回忆和复用这些信息。如果你正在构建需要长期记忆能力的 AI 应用或者希望现有的 AI 助手能够记住用户偏好和历史上下文EverOS 值得重点关注。这个项目的核心价值在于它的本地优先架构和 Markdown 原生存储。与依赖云端服务或复杂数据库的传统记忆系统不同EverOS 将对话和文件存储为可读的 Markdown 文件同时使用 SQLite 和 LanceDB 建立本地索引以实现快速检索。这种设计既保证了数据隐私和用户所有权又提供了 Git 友好的版本控制能力。1. 核心能力速览能力项说明项目类型Python 库 本地记忆运行时开源团队EverMind-AI核心功能AI 智能体长期记忆、对话记忆、文件记忆、跨会话上下文保持存储架构Markdown 源文件 SQLite LanceDB 三件套硬件要求本地运行无特殊 GPU 要求依赖 Python 3.12启动方式命令行启动服务REST API 接口调用API 支持完整的 OpenAI 协议兼容 API批量任务支持批量记忆添加、检索和索引构建适合场景AI 编码助手、多智能体系统、个人记忆助手、创意工具2. 适用场景与使用边界EverOS 最适合需要持久化记忆能力的 AI 应用场景。比如 AI 编码助手可以记住开发者偏好和项目上下文创意助手能够回顾过去的创作思路个人助理可以学习用户习惯并提供个性化服务。典型适用场景AI 编码助手的长时期上下文记忆多智能体协作系统的共享记忆层个人数字助手的习惯学习和偏好记忆创意工具的灵感追溯和上下文延续教育类应用的渐进式学习记忆使用边界提醒记忆数据涉及用户隐私部署时必须确保数据安全商业使用需遵守 Apache 2.0 许可证要求涉及个人敏感信息的应用需要明确的用户授权记忆检索的准确性依赖配置的 LLM 和嵌入模型能力3. 环境准备与前置条件在开始部署 EverOS 之前需要确保本地环境满足基本要求。系统要求操作系统Linux、macOS 或 WindowsWSL 推荐Python 版本3.12 或更高版本包管理工具uv 或 pipuv 推荐依赖检查# 检查 Python 版本 python --version # 应该显示 Python 3.12.x # 检查 uv 是否安装可选 uv --version磁盘空间基础安装约 100MB记忆存储根据使用量动态增长Markdown 文件格式相对节省空间网络要求初始安装需要下载依赖包运行时需要访问配置的 LLM 服务如 OpenRouter、DeepInfra4. 安装部署与启动方式EverOS 提供多种安装方式推荐使用 uv 进行依赖管理以获得更好的性能和隔离性。4.1 基础安装# 使用 uv 安装推荐 uv pip install everos # 或使用 pip 安装 pip install everos4.2 初始化配置安装完成后需要初始化配置文件# 生成默认配置文件 everos init这个命令会在当前目录创建.env文件包含需要配置的 API 密钥字段。4.3 配置 API 密钥编辑生成的.env文件配置必要的 API 密钥# 必需配置的 API 密钥 EVEROS_LLM__API_KEYyour_openrouter_key EVEROS_MULTIMODAL__API_KEYyour_openrouter_key EVEROS_EMBEDDING__API_KEYyour_deepinfra_key EVEROS_RERANK__API_KEYyour_deepinfra_key # 可选的基地址配置如果使用其他兼容服务 EVEROS_LLM__BASE_URLhttps://openrouter.ai/api/v14.4 启动记忆服务# 启动 EverOS 服务 everos server start服务默认在http://127.0.0.1:8000启动可以通过健康检查接口验证curl http://127.0.0.1:8000/health # 预期返回{status:ok}5. 功能测试与效果验证5.1 演示模式测试在配置 API 密钥前可以先运行演示模式了解记忆工作原理# 运行本地演示无需 API 密钥 everos demo演示模式会展示记忆的完整生命周期对话摄入 → 记忆提取 → 索引构建 → 回忆检索 → 来源验证。5.2 真实记忆流程测试配置好 API 密钥并启动服务后进行端到端测试# 使用实时演示模式连接运行中的服务 everos demo --live5.3 API 接口功能验证通过直接调用 API 验证核心记忆功能添加记忆TS$(($(date %s)*1000)) curl -X POST http://127.0.0.1:8000/api/v1/memory/add \ -H Content-Type: application/json \ -d { \session_id\: \test-session-001\, \app_id\: \test-app\, \project_id\: \test-project\, \messages\: [ {\sender_id\: \user123\, \role\: \user\, \timestamp\: $TS, \content\: \我喜欢在春天去西湖边散步。\}, {\sender_id\: \user123\, \role\: \user\, \timestamp\: $((TS10000)), \content\: \我常用的编程语言是 Python 和 JavaScript。\} ] }触发记忆提取curl -X POST http://127.0.0.1:8000/api/v1/memory/flush \ -H Content-Type: application/json \ -d {session_id:test-session-001,app_id:test-app,project_id:test-project}检索记忆curl -X POST http://127.0.0.1:8000/api/v1/memory/search \ -H Content-Type: application/json \ -d { user_id: user123, app_id: test-app, project_id: test-project, query: 我喜欢去哪里散步, top_k: 5 }预期成功标志添加接口返回 HTTP 200 状态码检索接口返回包含相关记忆的 JSON 响应在~/.everos目录下生成对应的 Markdown 记忆文件5.4 多模态文件支持测试如果需要处理图像、PDF 等非文本内容安装多模态扩展# 安装多模态支持 uv pip install everos[multimodal]Office 文档支持准备# macOS brew install --cask libreoffice # Ubuntu/Debian sudo apt-get install -y libreoffice6. 接口 API 与批量任务EverOS 提供完整的 REST API 接口支持批量记忆操作和自动化集成。6.1 核心 API 端点健康检查GET /health添加记忆POST /api/v1/memory/add Content-Type: application/json { session_id: string, app_id: string, project_id: string, messages: [ { sender_id: string, role: user|assistant, timestamp: 1234567890000, content: string } ] }记忆检索POST /api/v1/memory/search Content-Type: application/json { user_id: string, app_id: string, project_id: string, query: string, top_k: 5 }6.2 批量任务处理对于需要处理大量历史对话或文件的场景可以使用批量操作批量记忆添加示例Pythonimport requests import json from datetime import datetime def batch_add_memories(conversations, base_urlhttp://127.0.0.1:8000): 批量添加对话记忆 for i, conversation in enumerate(conversations): payload { session_id: fbatch-session-{i}, app_id: batch-import, project_id: historical-data, messages: conversation } response requests.post( f{base_url}/api/v1/memory/add, jsonpayload, timeout30 ) if response.status_code 200: print(f成功添加会话 {i}) else: print(f会话 {i} 添加失败: {response.text}) # 使用示例 conversations_batch [ [ {sender_id: user1, role: user, timestamp: 1234567890000, content: 对话内容1}, {sender_id: assistant1, role: assistant, timestamp: 1234567891000, content: 回复内容1} ], # ... 更多对话记录 ] batch_add_memories(conversations_batch)6.3 自动化集成模式对于生产环境建议实现重试机制和错误处理import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry class EverOSClient: def __init__(self, base_urlhttp://127.0.0.1:8000, timeout30): self.base_url base_url self.timeout timeout # 配置重试策略 retry_strategy Retry( total3, backoff_factor1, status_forcelist[429, 500, 502, 503, 504], ) adapter HTTPAdapter(max_retriesretry_strategy) self.session requests.Session() self.session.mount(http://, adapter) self.session.mount(https://, adapter) def search_memory(self, user_id, app_id, project_id, query, top_k5): 搜索记忆带错误处理 payload { user_id: user_id, app_id: app_id, project_id: project_id, query: query, top_k: top_k } try: response self.session.post( f{self.base_url}/api/v1/memory/search, jsonpayload, timeoutself.timeout ) response.raise_for_status() return response.json() except requests.exceptions.RequestException as e: print(f记忆搜索失败: {e}) return None # 使用示例 client EverOSClient() result client.search_memory(user123, my-app, project1, 用户偏好设置)7. 资源占用与性能观察EverOS 作为本地服务资源占用相对较轻主要消耗在 LLM API 调用和本地索引维护上。7.1 内存和存储占用内存占用基础服务约 100-200MB RAM索引构建时临时增加 50-100MB大量并发请求时按需增长存储占用Markdown 文件文本格式占用空间小SQLite 数据库存储索引和元数据LanceDB 向量索引随记忆数量线性增长7.2 性能优化建议索引优化# 定期优化数据库如果处理大量记忆 sqlite3 ~/.everos/memory.db VACUUM;批量操作策略大量记忆添加时使用批量接口减少 API 调用开销非实时场景可以累积一定量记忆后一次性处理重要记忆及时触发 flush 确保持久化监控指标API 响应时间正常情况应在 1-3 秒内记忆检索准确率通过测试查询验证存储增长趋势定期检查~/.everos目录大小8. 常见问题与排查方法问题现象可能原因排查方式解决方案服务启动失败Python 版本不兼容或依赖缺失检查 Python 版本和错误日志升级 Python 到 3.12重新安装依赖API 调用返回 401API 密钥未配置或无效检查 .env 文件配置验证 API 密钥有效性重新配置记忆检索为空索引尚未构建完成检查记忆是否已 flush调用 flush 接口后等待片刻再检索多模态解析失败LibreOffice 未安装或路径错误检查系统命令可用性安装 LibreOffice 并验证 soffice 命令端口冲突8000 端口被占用检查端口占用情况使用everos server start --port 新端口存储权限错误写入 ~/.everos 目录失败检查目录权限手动创建目录并设置正确权限8.1 详细故障排查流程服务启动问题排查# 1. 检查 Python 版本 python --version # 2. 验证安装 everos --version # 3. 检查配置文件 cat .env | grep -v KEY # 查看配置隐藏密钥 # 4. 查看详细错误日志 everos server start --verbose记忆检索问题排查# 1. 验证服务健康状态 curl http://127.0.0.1:8000/health # 2. 检查记忆是否成功添加 curl http://127.0.0.1:8000/api/v1/memory/add -X POST -H Content-Type: application/json -d {session_id:test,app_id:test,project_id:test,messages:[]} # 3. 手动触发索引构建 curl http://127.0.0.1:8000/api/v1/memory/flush -X POST -H Content-Type: application/json -d {session_id:test,app_id:test,project_id:test} # 4. 检查生成的 Markdown 文件 ls -la ~/.everos/9. 最佳实践与使用建议9.1 记忆结构设计会话组织策略按项目划分project_id保持记忆上下文相关性使用有意义的session_id便于后续管理和检索为不同用户分配独立的user_id确保隐私隔离记忆内容优化重要信息在对话中明确表述便于提取关键记忆定期总结和提炼核心记忆点避免过于碎片化的记忆内容9.2 生产环境部署安全配置# 使用环境变量而非文件存储敏感配置 export EVEROS_LLM__API_KEYyour_key export EVEROS_EMBEDDING__API_KEYyour_key everos server start服务监控# 简单的健康检查脚本 #!/bin/bash while true; do response$(curl -s http://127.0.0.1:8000/health) if [ $(echo $response | jq -r .status) ! ok ]; then echo 服务异常重启中... everos server start fi sleep 30 done9.3 性能调优索引优化定期清理测试记忆避免索引膨胀对于大量历史数据考虑分项目存储监控检索性能适时重建索引API 使用优化批量处理记忆添加请求减少网络开销使用异步处理非实时记忆操作实现客户端缓存减少重复检索10. 实际应用案例扩展10.1 AI 编码助手集成将 EverOS 集成到编码助手中可以记住开发者的技术偏好、项目架构决策和常见问题解决方案class CodingAssistantWithMemory: def __init__(self, everos_client): self.client everos_client self.current_project default def remember_technical_decisions(self, decision, rationale): 记录技术决策和原因 memory_data { session_id: ftech-decisions-{self.current_project}, app_id: coding-assistant, project_id: self.current_project, messages: [{ sender_id: system, role: user, timestamp: int(time.time() * 1000), content: f技术决策: {decision}. 原因: {rationale} }] } self.client.add_memory(memory_data) def recall_related_decisions(self, current_context): 检索相关技术决策 return self.client.search_memory( user_iddeveloper, app_idcoding-assistant, project_idself.current_project, querycurrent_context )10.2 多智能体系统记忆共享在多智能体协作场景中EverOS 可以作为共享记忆层class MultiAgentSystem: def __init__(self, everos_client): self.client everos_client self.agents {} def agent_conversation(self, agent1, agent2, topic, content): 记录智能体间对话 session_id fagent-chat-{agent1}-{agent2}-{topic} # 记录对话 self.client.add_memory({ session_id: session_id, app_id: multi-agent-system, project_id: collaboration, messages: [ { sender_id: agent1, role: user, timestamp: int(time.time() * 1000), content: content } ] }) def get_agent_context(self, agent, current_task): 为智能体提供相关上下文 memories self.client.search_memory( user_idagent, app_idmulti-agent-system, project_idcollaboration, querycurrent_task ) return self.format_context(memories)EverOS 为 AI 应用提供了坚实的记忆基础设施它的本地优先设计和 Markdown 原生存储使其在隐私保护和易用性方面具有明显优势。无论是增强现有 AI 助手的能力还是构建新的智能应用都值得尝试集成这一记忆层。