convez.ai
MCP ServerAutomaçãoAvançado
Justdoitfor

MemoCortex

Justdoitfor/memocortex

Infraestrutura distribuída de memória de longo prazo para agentes IA com arbitragem inteligente de conflitos

Ver no GitHub
InicialPluginScore · de 0 a 100

Middleware de memória de longo prazo agnóstico a agentes com 5 camadas de memória hierárquica, recall híbrido com 4 sinais (vetor + decaimento temporal + expansão em grafo + pontuação de importância) e resolução automática de conflitos com LLM-as-Arbitrator. Implementado como MCP Server para integração com múltiplos frameworks de IA.

Instalação

$npx convez-ai Justdoitfor/memocortex

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Agentes multiturno com memória persistente entre sessões
  • Sistemas que precisam gerenciar fatos conflitantes e atualizações de estado
  • Personificação de usuários com reflexão automática de perfil
  • Múltiplos agentes (LangChain, AutoGen, CrewAI) compartilhando contexto
  • Auditoria e rastreabilidade de evolução de conhecimento

Veredito

Solução sofisticada para o problema real de memória em agentes de longa duração. Diferencia-se pelo design em camadas (5 tipos vs. 2 concorrentes), resolução proativa de conflitos ao invés de ADD-only, e implementação como middleware MCP reutilizável. Exige expertise em sistemas distribuídos e LLMs para máximo aproveitamento.

README

A tradução para o português deste README ainda está na fila.

MemoCortex

Agent-agnostic 长期记忆中间件 — 5 类分层记忆 / 4 信号 Hybrid Recall / LLM-as-Arbitrator 冲突消解

Python FastAPI LangGraph MCP


解决什么问题

2026 年 Agent 落地最大的瓶颈不再是模型能力,而是长期记忆。MemoCortex 与现有方案的差异:

现状方案局限
LangChain ConversationSummaryMemory摘要损失大,跨 session 几乎全丢
mem0 v2.0.x (2026-04) — 已支持 Hybrid Retrieval + entity linking仍是 2 类扁平记忆;走 ADD-only + 召回 rerank 路线,对"用户搬家、换工作"这类确定性事实变更不主动收敛(旧事实留库靠 rank 压下去);无 MCP 协议接入
Zep强在时序检索,弱在多框架接入与冲突主动消解
Letta (原 MemGPT)单 Agent OS 风格,不是中间件

MemoCortex 把"记忆"当成一个分布式基础设施来做, 而不是某个 Agent 的内部模块:

  • 5 类分层记忆 (借鉴 Tulving 1985 认知科学分类), 信息按性质分流, 比 mem0 v2 的 2 类 + entity 多 3 个语义维度
  • 4 信号 Hybrid Recall (向量 + 时间衰减 + 图扩展 + 重要度评分), 比 mem0 v2 的 3 信号(语义 + BM25 + entity)多了"时间衰减"和"重要度"两个 mem0 没有的维度
  • LLM-as-Arbitrator 自动冲突消解 (REPLACE/MERGE/VERSIONED/IGNORE 4 种 action + 完整审计日志) — 与 mem0 v2 的 ADD-only 路线分歧,选择"写入时主动消解、可回滚可审计"
  • MCP Server (5 个工具) — mem0/Zep/Letta 都没做
  • Reflective Memory 用户画像 — 后台 Worker 周期刷新,作为"人物简介"注入 SystemPrompt
  • 多框架 Adapter (LangChain 已实现 + AutoGen/CrewAI stub) — 一次开发覆盖全 Agent 生态

30 秒上手

# 1. 安装 (含 chromadb / sentence-transformers / langchain 等)
uv sync --all-extras

# 2. (可选) 配置 LLM Key, 否则 semantic 抽取 / 冲突仲裁会走启发式降级
cp .env.example .env
# 编辑 .env: MEMOCORTEX_LLM_API_KEY=sk-...

# 3. 跑基础 demo (无需 LLM key 即可跑通主链路)
make demo

预期输出 (截取):

【Hybrid Recall】 4 信号融合召回
  Q: "运动相关"   (latency=20ms)
    [1] episodic    score=0.587  (vec=0.72 temp=1.00 graph=0.00 imp=0.50)  -> 晚上慢跑了 5 公里
    [2] episodic    score=0.586  ...                                       -> 看了一部关于量子物理的纪录片
    [3] episodic    score=0.577  ...                                       -> 下午去图书馆读了一本心理学的书

  召回延迟: P50=18.2ms  P95=19.6ms

架构

┌────────────────────────────────────────────────────────────────────┐
│                     上游 Agent 框架 (任意)                          │
│  LangChain     AutoGen      CrewAI      Custom (MCP Client)        │
│  + Adapter     + Stub       + Stub      ↓                          │
└──────────────────────┬─────────────────────────────────────────────┘
            统一接口: REST / Python SDK / MCP
                        │
┌───────────────────────▼────────────────────────────────────────────┐
│                     MemoCortex Core                                │
│                                                                    │
│  Memory Orchestrator   →   write / search / get_profile / forget   │
│                                                                    │
│  ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │ Working │ │ Episodic │ │ Semantic │ │Procedural│ │Reflective│  │
│  │ (LRU)   │ │ (Vec)    │ │ (KG+Vec) │ │ (Vec)    │ │ (Profile)│  │
│  └─────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
│                                                                    │
│  Hybrid Recall Router (4 信号融合 + 重排)                          │
│  Conflict Arbitrator (LLM-as-Judge → REPLACE/MERGE/VERSIONED/IGNORE)│
│  Reflection Workers (APScheduler 4 个周期任务)                     │
└───┬────────────┬──────────────┬──────────────┬────────────────────┘
    │            │              │              │
┌───▼───────┐ ┌──▼───────┐ ┌───▼──────┐ ┌─────▼──────┐
│ ChromaDB  │ │ NetworkX │ │ SQLite + │ │ 本地 FS    │
│ (向量)    │ │ (KG)     │ │SQLAlchemy│ │ (Cold)     │
└───────────┘ └──────────┘ └──────────┘ └────────────┘
   ⇩ 生产替换 (改一行 import 即可, 业务代码不动)
Milvus      Neo4j        PostgreSQL     S3/MinIO

5 类分层记忆

类型类比人类存储召回时机
Working短期记忆内存 LRU + SQLite 备份当前对话每轮
Episodic情景记忆ChromaDB + SQLite显式 search / 新对话开始时 RAG 注入
Semantic语义记忆NetworkX KG + ChromaDB 双索引每轮按实体匹配注入
Procedural程序性记忆ChromaDB + 任务模板Agent 决策 "我以前怎么做" 时
Reflective元记忆 / 用户画像SQLite JSONB每轮注入到 SystemPrompt

4 信号 Hybrid Recall

final_score = w1·vector_sim + w2·temporal_decay + w3·graph_proximity + w4·importance
  • vector_sim — ChromaDB cosine similarity
  • temporal_decay — exp(-Δt/τ), τ 默认 30 天
  • graph_proximity — Neo4j-style BFS, 共现实体距离 ≤ 2 跳加分
  • importance — 入库 LLM 打分, recall_count 饱和加成

权重可配 (.env), 也可通过 Optuna 在 LongMemEval 上自动调权 (留接口).


LLM-as-Arbitrator 冲突消解

新事实  →  Entity Extraction  →  KG 查冲突  →  LLM 仲裁
                                                  ↓
                                     ┌─────────────────────────┐
                                     │ REPLACE / MERGE /        │
                                     │ VERSIONED / IGNORE      │
                                     └─────────────────────────┘
                                                  ↓
                                          应用 + 写审计日志

举例:用户先说 "我对花生过敏",后说 "其实芝麻也过敏"。

  • mem0 v2 (2026-04+): ADD-only + 哈希去重,两条事实并存,靠召回 rank 处理 — 体验上"花生"还会被召回,得让上层 Agent 自己挑
  • MemoCortex: 识别 allergic_to 是 list 字段 → LLM 主动 MERGE → KG 中只保留一条合并后的多值事实,带审计日志可回滚 ✅

API 一览

入口端点说明
RESTPOST /v1/memories写入
RESTPOST /v1/memories/searchHybrid 召回
RESTGET /v1/users/{id}/profileReflective Profile
RESTGET /v1/users/{id}/entities/{name}KG 查询
RESTPOST /v1/memories/forgetGDPR 删除
RESTPOST /admin/reflect/{user_id}手动触发反思
RESTGET /admin/arbitrations/{user_id}冲突审计日志
RESTGET /metrics进程指标 (延迟/计数/cost)
Python SDKMemoCortexClient.write/search/...同步 + 异步 client
MCPmemory_write / memory_search / memory_get_profile / memory_forget / memory_list_arbitrations任意 MCP 客户端可接入

启动:

make api    # FastAPI → http://localhost:8765/docs
make mcp    # MCP Server → http://localhost:8766/mcp

评测体系

make eval-cn        # 8 个中文冲突仲裁场景 (REPLACE/MERGE 全覆盖)
make eval-longmem   # LongMemEval 子集 (需先下载数据集)
make eval           # 全套

每次跑分:

  • 落盘 tests/eval/.last_eval_score
  • 入 SQLite eval_runs 表 (跨版本回归对比)
  • 跨版本对比输出 本次 80% / 上次 75% ↑ +5%

8 个中文场景:用户搬家(REPLACE) / 过敏原合并(MERGE) / 跳槽(REPLACE) / 多养宠物(MERGE) / 爱好新增(MERGE) / 年龄变更(REPLACE) / 多语言(MERGE) / 长期事件召回。

LongMemEval 子集:留扩展点,完整跑分步骤见 tests/eval/longmemeval/adapter.py。


与 mem0 / Zep / Letta 的区别 (已对齐 mem0 v2.0.4, 2026-05 最新版)

维度mem0 v2.0.4 (2026-05)ZepLetta (MemGPT)MemoCortex
记忆分层2 类 (user / agent memory) + entity collection时序为主单 Agent OS 风格5 类 (Working/Episodic/Semantic/Procedural/Reflective)
召回信号3 信号融合 (语义 + BM25 + entity boost,v2 新增)向量 + 时序上下文窗口管理4 信号 (向量 + 时间衰减 + 图扩展 + 重要度)
冲突消解ADD-only + 哈希去重 + 召回 rank (v2 新路线)部分支持不强LLM Arbitrator + 4 action + 完整审计可回滚
知识图谱内置 entity linking (v2 移除 Neo4j)无无NetworkX KG (MVP) / Neo4j (生产) + entity 双索引
MCP Server❌❌❌✅ 5 个工具
Reflective Profile❌❌❌✅ 后台 Worker 周期刷新
多框架支持Python SDK + Platform API自有 SDK自有 SDKREST + SDK + MCP + LangChain Adapter
定位Agent 内部模块时序记忆库Agent OSAgent-agnostic 基础设施中间件

mem0 v2 (2026-04 发布) 做了架构级重写, 在 Hybrid Retrieval 和 entity linking 上追上了一代差距,但路线选择完全不同:

  • mem0 v2 选择: 写入侧极简 (ADD-only), 召回侧重 rank, 强调低延迟
  • MemoCortex 选择: 写入侧主动消解 (LLM Arbitrator + 审计), 召回侧 4 信号融合, 强调可解释与可回滚

两条路线在不同业务场景各有取舍。MemoCortex 更适合需要"用户画像稳定、事实变更可追溯"的企业场景。


项目结构

memocortex/
├── app/
│   ├── config.py                 # Pydantic Settings, 全 env 驱动
│   ├── models.py                 # 全部数据模型 (MemoryRecord/Triple/ArbitrationDecision/...)
│   ├── core/                     # LLM 工厂 / Embedding
│   ├── storage/                  # Protocol + 4 个 MVP 实现 (Chroma/NX/SQLite/FS)
│   ├── memories/                 # 5 类记忆
│   ├── recall/                   # Hybrid Router + 4 信号
│   ├── arbitrator/               # 冲突仲裁
│   ├── reflection/               # APScheduler 4 个周期任务
│   ├── orchestrator/             # read/write/search/forget 统一入口
│   ├── api/                      # FastAPI 路由
│   ├── sdks/                     # Python SDK (sync + async)
│   ├── adapters/                 # LangChain (实做) + AutoGen/CrewAI (Stub)
│   └── utils/                    # logger / metrics / token_meter
├── mcp_server/                   # fastmcp Server (5 个工具)
├── examples/
│   ├── demo_basic.py             # 5 类记忆 + Hybrid Recall (30 行)
│   ├── demo_conflict.py          # 4 种 ConflictAction 演示
│   └── demo_langchain.py         # 跨 session 长期记忆
├── tests/
│   ├── unit/                     # 23 个单元测试
│   └── eval/
│       ├── cn_scenarios/data/    # 8 个中文场景
│       ├── longmemeval/          # LongMemEval 适配
│       ├── runner.py             # 评测 runner
│       ├── judge.py              # LLM-as-Judge
│       └── metrics.py            # Recall@K / Precision@K / MRR / F1
├── pyproject.toml                # uv 管理
├── Makefile                      # 一站式命令
└── .env.example                  # 配置模板

技术栈

类别MVP 选型生产替换路径
WebFastAPI + Uvicorn + sse-starlette不变
AgentLangChain + LangGraph不变
LLMlangchain-openai (OpenAI 兼容,默认 DeepSeek)不变
EmbeddingHuggingFace bge-small-zh-v1.5 (本地)改 MEMOCORTEX_EMBEDDING_MODEL 即可
向量库ChromaDB 内嵌langchain-milvus / pgvector
知识图谱NetworkX + JSONneo4j-driver
关系数据SQLite + SQLAlchemy 2.0asyncpg + PostgreSQL
任务队列APScheduler 内存Celery + Redis
冷存储本地文件boto3 / minio SDK
MCPfastmcp + langchain-mcp-adapters不变

所有 MVP 简化项都通过 Protocol 抽象, 业务代码只依赖 app/storage/base.py 的接口, 生产替换不动业务代码。


Roadmap

  • Phase 1-7 MVP (本仓库)
  • LongMemEval 全量 500 题跑分
  • AutoGen / CrewAI Adapter 完整实现
  • 多模态记忆 (图片 / 音频, CLIP Embedding)
  • 跨用户共享记忆 + 团队 ACL
  • Optuna 自动召回权重调优
  • GDPR 严格合规 (加密 / 删除证明)
  • Prometheus 标准 metrics + Grafana 模板
  • Kubernetes Helm Chart

License

MIT

Ver o original no GitHub

Bom para

Relacionados