Kortexio Memory

试用（3 条命令） · 引擎 · 文档 · 与 Mem0 / Zep / Letta 对比

为你的 llama.cpp / vLLM 服务提供可自托管的记忆网关。

在你的引擎前接入一个兼容 OpenAI 的 /v1 URL。客户端只发送新消息； 网关会将会话记忆保存为可打开、编辑和比较差异的 Markdown。无需向量数据库，也无需重写客户端。

---

三条命令即可试用

git clone https://github.com/Kortexio/ContextMemory.git && cd ContextMemory
docker compose -f docker-compose.yml -f docker-compose.llamacpp.yml up --build -d   # CPU; GPU: docker-compose.vllm.yml
./scripts/aha-chat.sh                                                             # Windows: .\scripts\aha-chat.ps1

aha-chat 会在同一会话中发送两次请求。第二次请求仅包含新问题：

==> Turn 1: "Remember this for later: our staging database host is postgres-staging-01."
==> Turn 2: "What is our staging database host?"   (no history in the request body)
AHA OK — the client sent no history; the gateway remembered 'postgres-staging-01'.

每次推送时，CI 也会针对真实的 llama-server 运行相同检查（e2e-llamacpp）。首次启动时会下载约 2 GB 的 GGUF；使用 LLAMACPP_HF_MODEL 选择其他模型（引擎）。管理界面：http://localhost:5200。

---

什么是 ContextMemory？

ContextMemory 是 Kortexio 背后的开源Agent 式记忆网关。

你的应用（或 Cursor/Claude）继续使用普通聊天 API。网关会：

1. 对租户进行身份验证，并附加会话 wiki + 历史记录
2. 启用工具后运行Agent 式工具循环（wiki 搜索、沙箱、MCP 等）
3. 在执行破坏性操作前应用技能、护栏、验证器和可选的人工介入（HITL）
4. 返回标准的 OpenAI 格式 chat.completions 响应（支持流式传输）

Your client (OpenAI SDK / Cursor MCP / curl)
        │
        ▼  POST /v1/chat/completions
┌────────────────────────────────────────────┐
│  ContextMemory (.NET 9)                    │
│  Auth · session wiki · Global Wiki tool    │
│  Agentic loop · skills · guardrails · HITL │
│  LLM backend (per app — BYO engine)        │
└───────┬──────────────────┬─────────────────┘
        ▼                  ▼
 sandbox-runtime      mcp-runtime / MCP servers
 (shell/python/node)  (HTTP + stdio, OAuth)
 or Azure ACA sessions

明确的边界：这是一个网关 + 服务端运行框架，不是客户端 Agent 框架（LangGraph/CrewAI），也不是 Agent 操作系统（Letta）。你继续使用自己的 OpenAI 客户端；循环在服务端运行。

大模型引擎：ContextMemory 不会捆绑或锁定到某一种推理技术栈。你可以为每个租户选择任意兼容 OpenAI 的 /v1 主机——Ollama、vLLM、LM Studio、ExLlamaSharp、OpenAI、兼容 Azure 的服务、LiteLLM 或自定义服务。Compose 提供 llama.cpp 和 vLLM 覆盖配置；可在管理 → 配置 → LLM中为每个应用切换引擎。

对比说明（Mem0 / Zep / Letta / 为何我们不是 RAG）：docs/compare.md。

---

它为开发者提供什么

你需要……	ContextMemory 提供……
无需重写客户端、跨轮次保留的记忆	会话 Markdown 知识库 + 历史记录注入；只发送新消息
可打开、编辑和审计的记忆	磁盘文件 / Postgres，而非不透明的嵌入向量
在聊天中共享公司 / 文档知识	全局知识库摘要 + 按需使用 wiki_search / wiki_grep（不是经典 RAG / 嵌入向量）
无需第二个编排器即可使用工具	同一个 /v1：沙箱 + MCP + 知识库工具
更安全的 Agent	技能与护栏包、验证器、HITL [CONFIRM:id]
让 Cursor / Claude 快速拥有永久记忆	MCP 切入点：memory_save / memory_search / memory_get
每个租户使用任意 LLM	自带 /v1 — Ollama、vLLM、LM Studio、ExLlamaSharp、OpenAI、兼容 Azure 的服务、自定义服务
无需测试客户端即可运行	管理后台 + 游乐场
完全掌控 / 零运维	Docker 自托管 · Kortexio Cloud（cmk_live_…）

---

功能（摘要）

完整详情：docs/architecture-and-features.md · 管理后台：docs/admin-ui.md · HITL：docs/hitl.md。

领域	亮点
记忆	会话知识库 + 滚动摘要；历史记录预算；全局知识库摘要 / FTS / 修订版（asOf）；无向量 RAG
Agentic	服务端工具循环；沙箱；MCP 目录；制品；子 Agent；验证器；HITL；出口策略
技能	平台级 + 每个应用的技能 / 护栏（skill / always_on / requestable）
MCP	出站切入点（Cursor → CM）· 入站目录（CM → 你的 MCP 服务）
运维	管理界面 · 文件或 Postgres · Prometheus /metrics · Compose（API + 管理后台 + mcp-runtime + 沙箱）

 

---

更多运行方式

网关通过兼容 OpenAI 的 /v1 与引擎通信（需要 num_ctx 时使用 Ollama 原生 /api/chat）。随时可在管理后台 → 配置 → LLM 或 PATCH /admin/apps/{id}/config 中更换引擎。

引擎已在运行（llama-server、vLLM、LM Studio 等）— 仅 API 镜像

docker run --rm -p 5100:8080 \
  -v contextmemory-data:/app/data \
  -e ContextMemory__MasterKey=cm_master_dev_key_change_me \
  -e ContextMemory__Apps__demo-dev__ApiKey=cm_live_dev_key_change_me \
  -e ContextMemory__Apps__demo-dev__LlmBackend=openai-compatible \
  -e ContextMemory__Apps__demo-dev__LlmModel=local-model \
  -e ContextMemory__Apps__demo-dev__LlmEndpoint=http://host.docker.internal:8080 \
  --add-host=host.docker.internal:host-gateway \
  ghcr.io/kortexio/contextmemory:latest

适用于所有应用的主机级默认值：ContextMemory__LlmEndpoint。主机上的 Ollama 也可正常使用（ContextMemory__LlmEndpoint=http://host.docker.internal:11434）。重要的引擎标志（llama.cpp --jinja、vLLM 工具解析器）：引擎。完整技术栈（API + 管理后台 + MCP + 沙箱）：docs/self-host.md。

Cursor / Claude 记忆（MCP）

git clone https://github.com/Kortexio/ContextMemory.git
cd ContextMemory/mcp-server && npm install && node print-mcp-config.mjs

将其粘贴到Cursor → 设置 → MCP（或 ~/.cursor/mcp.json）。同一段配置也适用于 Claude Desktop。详情：mcp-server/README.md。

然后，在两个独立的聊天中：

聊天	你说	Agent 应执行
A	Remember: staging DB is postgres-staging-01	memory_save
B（新聊天）	What is our staging DB?	memory_search + 回答

不使用 Cursor 也能执行同一流程（知识库 API，无 LLM）：./scripts/aha-demo.sh 或 .\scripts\aha-demo.ps1。

无 GPU、无运维：Kortexio Cloud

	Kortexio Cloud	自托管（此仓库）
适用场景	零运维	完全掌控（API + 管理后台 + MCP + 沙箱）
密钥	cmk_live_…（无需 X-App-Id）	cm_live_… + X-App-Id
聊天请求体	与 OpenAI /v1 完全相同	与 OpenAI /v1 完全相同
LLM	在控制面板中自带服务提供商	在管理后台 / 环境变量中自带引擎

指南：Cloud · 自托管

即插即用聊天

curl -X POST http://localhost:5100/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-App-Id: demo-dev" -H "X-User-Id: user-42" -H "X-Session-Id: sess-abc" \
  -H "Authorization: Bearer cm_live_dev_key_change_me" \
  -d '{"model":"local-model","messages":[{"role":"user","content":"Hello"}]}'

轻量级请求头辅助工具（不是完整 SDK）：@kortexio/contextmemory · kortexio-contextmemory

---

文档与支持

文档	主题
docs/compare.md	存在的原因 · 与 Mem0 / Zep / Letta 的对比 · 为什么我们不是 RAG
docs/architecture-and-features.md	Wiki、时序事实、智能体、技能、大模型后端
docs/admin-ui.md	管理界面概览
docs/hitl.md	人机协作
docs/api.md	HTTP API
docs/cloud.md · docs/self-host.md	云端 · Docker / Compose
docs/ops.md	运维与故障排查
docs/README.md	完整文档索引

网站：kortexio.io · 邮箱：[email protected]

---

许可证

此开源核心采用 AGPL-3.0 许可证——可自由自托管，包括用于商业用途。需要将其嵌入闭源产品，且不受 AGPL 义务约束？请使用 Kortexio Cloud 或商业许可证。请参阅 docs/license-and-support.md。