EverOS：基于Markdown的AI智能体本地长期记忆管理解决方案

在AI应用开发中长期记忆管理一直是个技术难点。传统方案要么依赖复杂的云端服务要么难以实现跨应用的数据同步。EverOS作为一款本地优先的Python内存运行时库通过Markdown原生存储和本地索引技术为AI智能体提供了可移植的记忆层解决方案。本文将完整介绍EverOS的核心特性、安装配置、API使用和实际应用场景。1. EverOS核心概念与架构解析1.1 什么是EverOSEverOS是一个专为AI智能体和开发者设计的Python库它提供了一个本地优先的内存运行时环境。与传统的内存管理方案不同EverOS采用Markdown作为数据存储的源格式结合SQLite和LanceDB构建本地索引实现了对话记录、文件内容和智能体轨迹的可读、可编辑、可版本控制的持久化存储。EverOS的核心设计理念是一次编写处处可用——为编码助手、应用程序、设备和工作流提供统一的便携记忆层。这意味着开发者可以在不同的AI应用之间共享和复用记忆数据而无需担心数据格式兼容性问题。1.2 技术架构优势EverOS的三层架构设计是其技术优势的关键所在Markdown源存储层所有记忆数据都以标准的Markdown格式存储这使得文件可以直接用文本编辑器查看和修改也便于使用Git进行版本控制。这种设计确保了数据的长期可读性和可维护性。SQLite关系索引层用于存储结构化的元数据和关系信息支持快速的关系查询和事务操作。SQLite的轻量级特性使得EverOS可以在资源受限的环境中运行。LanceDB向量索引层专门处理语义搜索和相似性匹配支持基于嵌入向量的高效检索。LanceDB的列式存储特性优化了大规模向量数据的查询性能。这种架构与传统方案的对比优势明显传统方案通常依赖MongoDB、Elasticsearch或Redis等外部服务而EverOS的本地化设计降低了部署复杂度提高了数据隐私性。1.3 核心特性详解正交检索能力EverOS支持基于user_id、agent_id、app_id、project_id和session_id的多维度检索。这种设计使得记忆数据可以在不同的应用场景中被灵活复用而不会出现数据污染或权限冲突。知识维基功能内置的Markdown知识页面管理系统支持分类、CRUD API和主题搜索将知识管理直接集成到记忆层中而不是作为独立的功能模块。反射式记忆进化EverOS能够在会话之间离线合并事件集群优化用户画像和技能描述实现记忆的自我进化。这与传统的仅检索式记忆系统相比具有明显的长期学习优势。2. 环境准备与安装配置2.1 系统要求与依赖EverOS要求Python 3.12或更高版本。在开始安装前请确保系统满足以下要求# 检查Python版本 python --version # 应该显示 Python 3.12.x 或更高 # 确保pip或uv包管理器可用 pip --version # 或者 uv --version对于多模态文件处理功能还需要安装LibreOffice作为系统依赖# macOS系统 brew install --cask libreoffice # Ubuntu/Debian系统 sudo apt-get install -y libreoffice # CentOS/RHEL系统 sudo yum install libreoffice2.2 安装EverOS推荐使用uv包管理器进行安装这能确保依赖关系的正确解析# 使用uv安装 uv pip install everos # 或者使用pip安装 pip install everos如果需要多模态文件支持图像、PDF、音频、Office文档等安装时需指定额外依赖# 安装完整的多模态支持版本 uv pip install everos[multimodal] # 或者使用pip pip install everos[multimodal]多模态版本会额外安装everalgo-parser库并提供SVG支持通过cairosvg。Office文档处理依赖LibreOffice的soffice命令行工具进行格式转换。2.3 API密钥配置虽然演示模式不需要API密钥但生产环境需要配置LLM和嵌入模型服务。EverOS支持多种OpenAI兼容的提供商# 初始化配置文件 everos init这会生成.env配置文件需要填入以下API密钥# .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 # 可选的Base URL重写如果使用其他提供商 EVEROS_LLM__BASE_URLhttps://openrouter.ai/api/v1 EVEROS_EMBEDDING__BASE_URLhttps://api.deepinfra.com/v1/openai配置文件搜索优先级为命令行指定→当前目录→XDG配置目录→用户主目录。3. 快速入门与实践演示3.1 演示模式体验在配置API密钥前可以先体验本地演示模式了解EverOS的工作流程# 运行交互式演示 everos demo # 影院模式循环展示 everos demo --cinematic # 纯文本模式适合非交互式环境 everos demo --plain演示模式会展示完整的内存生命周期对话输入→记忆球处理→检索→源验证→确认动画。按r键重播按q键退出。3.2 启动EverOS服务配置好API密钥后可以启动本地服务# 启动服务默认端口8000 everos server start # 验证服务状态 curl http://127.0.0.1:8000/health # 预期响应: {status:ok}服务启动后会自动检测.env配置文件并建立本地的Markdown存储和索引数据库。3.3 连接实时演示在服务运行状态下可以体验实时演示# 连接运行中的服务进行演示 everos demo --live # 如果服务不在默认地址指定服务URL everos demo --live --server-url http://localhost:8000实时演示会执行完整的API调用流程健康检查→记忆添加→刷新→搜索让开发者直观了解系统的工作机制。4. API使用详解与实战示例4.1 记忆添加APIEverOS的核心API设计遵循RESTful风格记忆添加端点支持结构化对话数据# 生成时间戳Unix毫秒 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\: \demo-001\, \app_id\: \default\, \project_id\: \default\, \messages\: [ { \sender_id\: \alice\, \role\: \user\, \timestamp\: $TS, \content\: \I love climbing in Yosemite every spring.\ }, { \sender_id\: \alice\, \role\: \user\, \timestamp\: $((TS10000)), \content\: \My favorite coffee shop is Blue Bottle in SOMA.\ } ] }Python客户端的使用示例import requests import time def add_memory_example(): base_url http://127.0.0.1:8000/api/v1 timestamp int(time.time() * 1000) memory_data { session_id: python-demo-001, app_id: test-app, project_id: demo-project, messages: [ { sender_id: user123, role: user, timestamp: timestamp, content: 我正在学习Python机器学习库scikit-learn }, { sender_id: user123, role: user, timestamp: timestamp 5000, content: 特别是决策树和随机森林算法 } ] } response requests.post(f{base_url}/memory/add, jsonmemory_data) return response.json() # 执行示例 result add_memory_example() print(记忆添加结果:, result)4.2 记忆刷新与提取添加记忆后需要触发提取流程将对话内容转化为结构化的记忆实体# 强制刷新指定会话的记忆提取 curl -X POST http://127.0.0.1:8000/api/v1/memory/flush \ -H Content-Type: application/json \ -d { session_id: demo-001, app_id: default, project_id: default }刷新操作会启动后台处理流程包括对话内容解析和实体提取关系建立和分类Markdown文件生成向量索引更新4.3 记忆搜索API搜索API支持多条件查询和语义匹配# 基于用户和查询条件搜索记忆 curl -X POST http://127.0.0.1:8000/api/v1/memory/search \ -H Content-Type: application/json \ -d { user_id: alice, app_id: default, project_id: default, query: Where do I like to climb?, top_k: 5 }高级搜索示例import requests def advanced_search_example(): base_url http://127.0.0.1:8000/api/v1 search_params { user_id: user123, app_id: test-app, project_id: demo-project, query: 机器学习算法学习进度, top_k: 10, min_score: 0.7, # 最小匹配分数阈值 include_sources: True # 包含源文件信息 } response requests.post(f{base_url}/memory/search, jsonsearch_params) results response.json() print(搜索到, len(results.get(results, [])), 条相关记忆) for i, result in enumerate(results.get(results, [])): print(f{i1}. 内容: {result[content]}) print(f 匹配度: {result[score]:.3f}) if result.get(sources): print(f 来源: {result[sources][0][file_path]}) return results # 执行高级搜索 search_results advanced_search_example()5. 多模态文件处理实战5.1 支持的文件类型EverOS的多模态扩展支持丰富的文件格式处理图像文件: JPEG, PNG, GIF, BMP, SVG, WebP文档格式: PDF, HTML, 纯文本文件Office文档: DOC, DOCX, PPT, PPTX, XLS, XLSX需要LibreOffice音频文件: MP3, WAV, FLAC, OGG电子邮件: EML, MSG格式5.2 多模态记忆添加示例处理包含文件的记忆数据import base64 import requests def add_multimodal_memory(): 添加包含图像和文档的记忆示例 # 读取并编码图像文件 with open(diagram.png, rb) as image_file: image_data base64.b64encode(image_file.read()).decode(utf-8) # 读取PDF文档 with open(report.pdf, rb) as pdf_file: pdf_data base64.b64encode(pdf_file.read()).decode(utf-8) memory_data { session_id: multimodal-demo, app_id: research-app, project_id: ai-research, messages: [ { sender_id: researcher, role: user, timestamp: int(time.time() * 1000), content: 这是我们的系统架构图和实验报告, content_items: [ { type: image, mime_type: image/png, data: image_data }, { type: document, mime_type: application/pdf, data: pdf_data } ] } ] } response requests.post( http://127.0.0.1:8000/api/v1/memory/add, jsonmemory_data ) return response.json() # 处理Office文档的注意事项 def check_office_support(): 检查Office文档支持状态 try: import subprocess subprocess.run([soffice, --version], checkTrue, capture_outputTrue) print(LibreOffice已安装支持Office文档处理) except (subprocess.CalledProcessError, FileNotFoundError): print(警告: LibreOffice未安装Office文档处理功能受限) print(PDF和图像处理功能正常可用) check_office_support() result add_multimodal_memory()5.3 文件处理流程详解多模态文件的处理遵循以下流程文件上传验证检查文件类型、大小和格式兼容性格式转换Office文档通过LibreOffice转换为PDF其他格式直接处理内容提取使用多模态LLM解析文件内容文本化存储提取的内容以Markdown格式存储索引建立文本内容进入向量数据库供搜索6. 存储结构与数据管理6.1 文件系统布局EverOS的本地存储采用标准化的目录结构~/.everos/ ├── apps/ # 应用数据目录 │ ├── default/ # 默认应用 │ │ ├── projects/ # 项目目录 │ │ │ └── default/ # 默认项目 │ │ │ ├── sessions/ # 会话数据 │ │ │ ├── knowledge/ # 知识页面 │ │ │ └── profiles/ # 用户画像 │ │ └── agents/ # 智能体数据 ├── indexes/ # 索引数据库 │ ├── sqlite.db # SQLite关系数据库 │ └── lancedb/ # LanceDB向量数据库 └── config/ # 配置文件 └── everos.toml # 运行时配置6.2 Markdown存储格式记忆数据以人类可读的Markdown格式存储# 会话: demo-001 应用: default · 项目: default · 用户: alice ## 记忆实体 ### 地点偏好 - **类型**: 偏好 - **主题**: 户外活动 - **内容**: 喜欢每年春天在Yosemite攀岩 - **置信度**: 0.92 - **提取时间**: 2025-01-15T10:30:00Z ### 商业偏好 - **类型**: 偏好 - **主题**: 餐饮 - **内容**: 最喜欢的咖啡店是SOMA的Blue Bottle - **置信度**: 0.88 - **提取时间**: 2025-01-15T10:30:05Z ## 原始对话 **alice** (10:25:00): I love climbing in Yosemite every spring. **alice** (10:25:10): My favorite coffee shop is Blue Bottle in SOMA.6.3 数据备份与迁移由于采用标准文件格式备份和迁移非常简单# 完整备份EverOS数据 tar -czf everos-backup-$(date %Y%m%d).tar.gz ~/.everos/ # 迁移到新机器 scp everos-backup-20250115.tar.gz usernewmachine:~/ ssh usernewmachine tar -xzf everos-backup-20250115.tar.gz # 增量备份仅备份变更 rsync -av ~/.everos/ /backup/everos-$(date %Y%m%d)/7. 高级功能与集成应用7.1 知识维基管理EverOS内置的知识维基系统支持完整的CRUD操作def knowledge_wiki_example(): 知识维基API使用示例 base_url http://127.0.0.1:8000/api/v1 # 创建知识页面 page_data { title: 机器学习基础概念, content: ## 监督学习\n- 分类问题\n- 回归问题\n\n## 无监督学习\n- 聚类分析\n- 降维技术, tags: [机器学习, AI, 教程], category: 技术文档 } # 创建页面 create_response requests.post( f{base_url}/knowledge/pages, jsonpage_data ) page_id create_response.json()[id] # 搜索知识内容 search_response requests.post( f{base_url}/knowledge/search, json{query: 监督学习分类回归, top_k: 5} ) return search_response.json() # 知识维基搜索结果通常包含 # - 页面标题和内容摘要 # - 相关度评分 # - 标签和分类信息 # - 直接编辑链接7.2 多应用集成模式EverOS支持多种集成方式适应不同的应用架构直接API集成适合Web应用class EverOSClient: def __init__(self, base_urlhttp://localhost:8000): self.base_url base_url def log_conversation(self, session_id, messages, app_iddefault): 记录对话到EverOS memory_data { session_id: session_id, app_id: app_id, project_id: default, messages: messages } response requests.post( f{self.base_url}/api/v1/memory/add, jsonmemory_data ) return response.json() def search_context(self, user_id, query, app_iddefault): 为当前对话搜索相关上下文 search_params { user_id: user_id, app_id: app_id, project_id: default, query: query, top_k: 3 } response requests.post( f{self.base_url}/api/v1/memory/search, jsonsearch_params ) return response.json().get(results, [])命令行工具集成适合脚本和自动化任务#!/bin/bash # 自动化脚本示例记录工作日志并搜索相关任务 # 记录当前工作内容 log_work() { local content$1 local timestamp$(($(date %s)*1000)) curl -s -X POST http://127.0.0.1:8000/api/v1/memory/add \ -H Content-Type: application/json \ -d { \session_id\: \work-log-$(date %Y%m%d)\, \app_id\: \work-automation\, \project_id\: \daily-tasks\, \messages\: [ { \sender_id\: \$(whoami)\, \role\: \user\, \timestamp\: $timestamp, \content\: \$content\ } ] } # 立即刷新确保可搜索 curl -s -X POST http://127.0.0.1:8000/api/v1/memory/flush \ -H Content-Type: application/json \ -d { session_id: work-log-$(date %Y%m%d), app_id: work-automation, project_id: daily-tasks } } # 搜索相关工作记录 search_work() { local query$1 curl -s -X POST http://127.0.0.1:8000/api/v1/memory/search \ -H Content-Type: application/json \ -d { \user_id\: \$(whoami)\, \app_id\: \work-automation\, \project_id\: \daily-tasks\, \query\: \$query\, \top_k\: 5 } | jq .results[] | {content, score} }7.3 记忆反射与自我进化EverOS的反射功能能够在后台优化记忆结构def trigger_reflection(): 手动触发记忆反射流程 reflection_params { user_id: alice, app_id: default, project_id: default, strategy: aggressive # 可选: conservative, moderate, aggressive } response requests.post( http://127.0.0.1:8000/api/v1/memory/reflect, jsonreflection_params ) return response.json() # 反射流程的主要作用 # 1. 合并相似记忆片段减少冗余 # 2. 更新用户画像基于新的行为模式 # 3. 优化智能体技能描述 # 4. 重建索引提高搜索效率8. 性能优化与生产部署8.1 配置调优建议针对生产环境的重要配置参数# ~/.everos/config/everos.toml [server] port 8000 workers 4 max_requests 1000 [indexing] batch_size 100 vector_dimension 1536 max_connections 20 [storage] auto_cleanup_days 30 max_file_size_mb 100 compression_enabled true [memory] reflection_interval_hours 24 max_entities_per_user 100008.2 监控与健康检查实现完整的监控方案import requests import time from prometheus_client import start_http_server, Gauge class EverOSMonitor: def __init__(self, base_url): self.base_url base_url self.health_gauge Gauge(everos_health, EverOS服务健康状态) self.response_time_gauge Gauge(everos_response_time, API响应时间) def check_health(self): 健康检查并收集指标 start_time time.time() try: response requests.get(f{self.base_url}/health, timeout5) response_time (time.time() - start_time) * 1000 self.response_time_gauge.set(response_time) if response.status_code 200: self.health_gauge.set(1) return True else: self.health_gauge.set(0) return False except requests.exceptions.RequestException: self.health_gauge.set(0) return False def run_monitoring(self): 启动监控循环 start_http_server(8001) # Prometheus指标端口 while True: self.check_health() time.sleep(30) # 每30秒检查一次 # 使用示例 monitor EverOSMonitor(http://localhost:8000) monitor.run_monitoring()8.3 高可用部署架构对于企业级部署建议采用以下架构客户端应用 → 负载均衡器 → EverOS实例集群 → 共享存储 ↘ 监控告警系统 → 日志聚合关键配置要点使用Nginx进行负载均衡共享存储层NFS或云存储保证数据一致性每个实例配置独立的本地缓存设置自动故障转移机制9. 常见问题与故障排除9.1 安装与配置问题问题1Python版本兼容性错误Error: EverOS requires Python 3.12 but you have Python 3.11.6解决方案# 使用pyenv管理多版本Python pyenv install 3.12.0 pyenv global 3.12.0 # 或者使用conda环境 conda create -n everos python3.12 conda activate everos问题2API密钥配置错误Error: Missing required API keys for LLM service解决方案# 检查当前生效的配置文件 everos config show # 重新初始化配置 everos init --force # 验证配置是否正确加载 python -c import os from dotenv import load_dotenv load_dotenv() print(LLM Key:, os.getenv(EVEROS_LLM__API_KEY)[:10] ...) 9.2 服务运行问题问题3端口占用冲突Error: Address already in use [::]:8000解决方案# 查看端口占用 lsof -i :8000 # 终止占用进程或使用其他端口 everos server start --port 8001 # 或者配置环境变量 export EVEROS_SERVER_PORT8001 everos server start问题4内存索引构建失败Error: LanceDB index corruption detected解决方案# 重建索引会重新处理所有Markdown文件 everos index rebuild # 或者仅检查索引状态 everos index verify # 清理临时文件 rm -rf ~/.everos/indexes/lancedb/temp-*9.3 性能优化问题问题5搜索响应缓慢解决方案# 优化搜索参数 optimized_search { query: 具体的关键词, top_k: 10, # 限制结果数量 min_score: 0.6, # 设置分数阈值 filter: { app_id: specific-app, # 添加过滤器 time_range: { start: 2025-01-01T00:00:00Z, end: 2025-01-31T23:59:59Z } } } # 使用批量操作减少API调用 def batch_memory_operations(memories): 批量处理记忆操作 with requests.Session() as session: for memory in memories: session.post( http://localhost:8000/api/v1/memory/add, jsonmemory ) # 一次性刷新 session.post(http://localhost:8000/api/v1/memory/flush)10. 实际应用场景与最佳实践10.1 AI编码助手集成将EverOS集成到开发工作流中class CodingAssistantWithMemory: def __init__(self, everos_client): self.everos everos_client self.current_session fdev-session-{int(time.time())} def log_development_context(self, file_path, code_context, task_description): 记录开发上下文 memory_data { session_id: self.current_session, app_id: code-assistant, project_id: os.path.basename(os.getcwd()), messages: [{ sender_id: getpass.getuser(), role: developer, timestamp: int(time.time() * 1000), content: f文件: {file_path}\n任务: {task_description}\n上下文: {code_context} }] } self.everos.add_memory(memory_data) def get_relevant_context(self, current_task): 获取相关开发上下文 results self.everos.search_memory({ user_id: getpass.getuser(), app_id: code-assistant, query: current_task, top_k: 3 }) context \n.join([f- {r[content]} for r in results]) return f相关历史上下文:\n{context} if context else 暂无相关历史记录10.2 客户服务对话管理在客服场景中应用长期记忆class CustomerServiceAgent: def __init__(self, everos_base_url): self.base_url everos_base_url def handle_customer_query(self, customer_id, query): 处理客户查询利用历史上下文 # 搜索该客户的过往交互 history self.search_customer_history(customer_id, query) # 构建包含上下文的提示 context self.build_context_string(history) enhanced_query f{context}\n当前问题: {query} # 处理当前查询调用LLM等 response self.process_query(enhanced_query) # 记录本次交互 self.record_interaction(customer_id, query, response) return response def search_customer_history(self, customer_id, current_query): 搜索客户历史记录 search_params { user_id: customer_id, app_id: customer-service, query: current_query, top_k: 5 } response requests.post( f{self.base_url}/api/v1/memory/search, jsonsearch_params ) return response.json().get(results, [])10.3 个人知识管理系统构建基于EverOS的PKM系统class PersonalKnowledgeManager: def __init__(self, everos_client): self.client everos_client def add_knowledge_item(self, title, content, tags, category): 添加知识条目 knowledge_data { title: title, content: content, tags: tags, category: category, app_id: pkm-system, project_id: personal-knowledge } return self.client.add_knowledge(knowledge_data) def search_knowledge(self, query, filtersNone): 搜索知识库 search_params { query: query, top_k: 10, filters: filters or {} } return self.client.search_knowledge(search_params) def generate_learning_path(self, topic): 基于已有知识生成学习路径 related_knowledge self.search_knowledge(topic) # 分析知识缺口和建议学习顺序 path self.analyze_knowledge_gaps(related_knowledge, topic) return path通过上述实践案例可以看出EverOS为各种AI应用场景提供了强大的长期记忆支持。其本地优先的设计理念确保了数据隐私而标准化的API接口使得集成变得简单直接。无论是开发智能助手、客户服务系统还是个人知识管理工具EverOS都能提供可靠的记忆层基础设施。