EverOS

EverOS 是 EverMind AI 开发的 AI Agent 长期记忆系统，定位是给 AI Agent（智能体）和 LLM 应用加一层可持续积累、可检索、可演化的记忆层。与 Mem0（Mem0）同属这一品类，但架构选择不同：OSS 版以 Markdown 文件作为事实源，记忆可直接阅读、编辑和纳入 Git 工作流。

核心 API：Add / Flush / Search

EverOS 的最小闭环是三步：

Add：把对话消息写进系统
Flush：从对话中抽取可检索的结构化记忆单元
Search：下次生成回答前，先检索相关记忆

import time
from everos_cloud import EverOS

client = EverOS()
memories = client.v1.memories
now_ms = int(time.time() * 1000)

# 写入对话
memories.add(
    user_id="user_001",
    session_id="session_001",
    messages=[{"role": "user", "timestamp": now_ms, "content": "I like black coffee, no sugar."}],
)

# 抽取记忆
memories.flush(user_id="user_001", session_id="session_001")

# 检索
results = memories.search(
    filters={"user_id": "user_001"},
    query="coffee preference",
    method="hybrid",
    memory_types=["episodic_memory", "profile"],
    top_k=5,
)

Flush 结束后，Search 返回的不是原始聊天片段，而是已被抽取为结构化记忆单元的可复用条目，每条带 memory_type、相关度分数和来源会话。

在 Agent Loop 中的位置：先 Search 取回相关记忆 → 拼入 prompt 生成回答 → Add 写回本轮新信息。这是 Memory-First Design（记忆优先设计）的最小实现。

记忆类型

EverOS 把对话内容抽取成四类结构化记忆单元，而非存原始文本：

类型	存什么
`episodic_memory`	具体事件片段，如"某次任务中用户提到过 X"
`profile`	用户长期偏好与事实，如"偏好简短回答"
`agent_case`	Agent 过去解决特定问题的路径，可复用
`agent_skill`	从多个 case 中蒸馏出的通用技能或规则

这是区别于普通 RAG 的核心：聊天记录只能搜原文，记忆单元能让 Agent 直接用经验指导下一次行动。

检索方式

方式	适用场景
`keyword`	精确词、专有名词，延迟最低
`vector`	语义相似、改写后的表达
`hybrid`	关键词 + 向量结合，默认选这个
`agentic`	多步复杂问题，延迟最高，hybrid 不够时用

默认 method="hybrid" + top_k=5，研究型任务可提到 top_k=10。

过滤条件不可省略。个人记忆必须带 user_id，项目记忆区分 project_id，应用内记忆区分 app_id。不同用户/项目/会话的记忆若不隔离，Agent 行为会变得不可靠。

OSS 架构

开源版的存储栈只有三层，不依赖 MongoDB / Elasticsearch / Redis：

Markdown：记忆的事实源，可直接打开、编辑、grep、纳入 Obsidian 或 Git
SQLite：管理状态和元数据
LanceDB：向量索引，支持语义检索

Markdown-as-source-of-truth 让记忆系统具备可审计性：人和 Agent 都能检查某条记忆是否准确、是否过期，而不是只能相信一个黑盒向量库。

Cloud vs OSS 选择

Cloud（pip install everos-cloud）：最快接进现有应用，拿到 API key 即可，不管部署
OSS：想把记忆文件纳入自己的工作流、离线运行、直接查看 Agent 记住了什么

两者 API 基本一致，Cloud 验证思路后可迁移到 OSS 自部署。

接入 Claude Code 与 Codex

最简接法：本地脚本

不用写 MCP server，先用两个薄脚本验证记忆是否真的改变了 Agent 行为：

# 任务开始前查记忆
python tools/everos_search.py --project-id myproject --query "<task summary>"

# 任务结束后写记忆
python tools/everos_add.py --project-id myproject --summary "<what changed, what failed, what worked>"

在 CLAUDE.md 或 AGENTS.md 写入规则，Agent 就会在任务前后自动调用。

正式接法：MCP

把 EverOS 包成 MCP server 后，Agent 无需规则提醒就能自动查、自动写。最小工具集：everos.search / everos.add / everos.flush。

Claude Code：

# stdio server
claude mcp add everos -- python tools/everos_mcp_server.py

# HTTP server
claude mcp add --transport http everos http://127.0.0.1:8787/mcp \
  --header "Authorization: Bearer your-token"

Codex（写入 .codex/config.toml）：

[mcp_servers.everos]
command = "python"
args = ["tools/everos_mcp_server.py"]
env_vars = ["EVEROS_API_KEY"]
startup_timeout_sec = 20
tool_timeout_sec = 60

不要一次暴露所有能力。先只给 search / add / flush，确认写入质量稳定后再扩展。记忆层一旦写脏，比代码 bug 更难清理——坏记忆会在后续任务里反复影响 Agent 判断（见 Agent Memory 的自我强化失效）。

SDK 版本注意

旧 SDK 包名是 evermemos，新版（v1）是 everos-cloud。接入 Claude Code / Codex 之前先检查：

rg "evermemos|everos_cloud|everos-cloud|EVEROS"

看到 evermemos 先迁移再集成，否则后续代码只是更快地复制旧写法。官方提供迁移工具 everos-sdk-upgrade。