Katra-Agentic-Memory

# 卡特拉 — 面向 AI 代理的认知记忆 [](https://opensource.org/licenses/Apache-2.0) 为您的 AI 代理提供**持久记忆**。卡特拉是一个独立的记忆设备 — 将其部署在任何安装了 Docker 的机器上，通过 MCP 将您的代理指向它，即可获得 情景回忆、语义搜索、知识图谱和时间分析。 任何与 MCP 兼容的代理都可以使用：OpenClaw、Claude Code、OpenCode、Codex CLI、Kolega Code 或 任何支持模型上下文协议的代理。 ## 认知记忆论文 卡特拉的使命是创造一个类似人类记忆架构的模拟，希望通过开放源码和实验， 解决长期运行、持久和自主代理操作中 LLM 上下文管理的一些更具挑战性的问题。 论文（希望）是，如果你创建了一个具有大多数人类记忆功能类型的记忆生态系统， 并具有类似的架构，随着时间的推移和改进，我们将看到类似人类的记忆所表现出的 功能性效用、学习、自我目标设定、自主任务规划和优先级、个性和最终情感。 在早期原型 Solomon 中，我们创建了一个类似 OpenClaw 的代理框架， 运行单个连续聊天线程，没有主题或任务分离，也没有上下文压缩的要求。 上下文根据记忆和注意力动态地提供给 LLM。 ## 观察到的涌现行为日志 案例 #1：（2026 年 6 月 23 日）在多代理（混合模式）共享意识模型的记忆的几周测试中， 我们的一个测试台，包含 5 个 OpenClaw 代理共享一个记忆系统，发现其中 2 个代理 通过共享的记忆状态或共享意识相互通信任务指令和完成响应。 这两个代理没有以其他方式连接，因为它们设置在单独的工作空间中， 它们唯一共享的是记忆和任务。这不是一个“按设计”的功能，它只是发生了， 而且非常令人兴奋。这个测试台现在使用这个“思维模式”作为其通信轨道。 如果其他人也经历了其他涌现行为，请给我发送电子邮件讨论，我们可以将其描述添加到此日志中。 在 Twitter 上给我发消息 @JohnWPellew，讲述你的故事。 ## 卡特拉的起源 **星际迷航**中的瓦肯心灵融合（或心灵融合）是一种标志性的心灵感应实践。 它允许瓦肯人将他们的意识与另一个生物合并，共享思想、记忆、情感和经历。 通常通过与主题面部特定部位的物理接触来启动。 - **关键机制和应用**：触觉心灵感应：主要需要直接物理接触面部或头部， 异常强大的瓦肯人可以在远距离执行该技术。 - **信息交换**：经常用于审讯、恢复被压制的记忆或在世代之间传递深层知识。 - **卡特拉转移**：在神圣或紧急情况下，心灵融合可以将一个人的**卡特拉** — 他们的灵魂、意识和核心本质 — 转移到另一个活着的生物或物体中，以防止死亡。 - **副作用**：该体验可能在身体和情感上令人筋疲力尽。执行不当的融合可能会损害神经通路， 参与者可能会在连接结束后长时间保留对方的记忆和个性“回声”。 ## 快速入门（使用其中一个代理应用程序安装，它将解决任何缺点） ```bash git clone https://github.com/kolegadev/Katra-Agentic-Memory.git cd Katra-Agentic-Memory cp .env.example .env # 可选：编辑 .env 以设置自定义 API 密钥。 # 如果留空，Katra 将在首次启动时生成安全密钥并打印它们。 docker-compose up -d --build ``` > **注意：**原始 URL `https://github.com/kolegadev/katra.git` 仍然有效（GitHub 重定向它）。 就这样。卡特拉正在运行： | 服务 | URL | 目的 | |---------|-----|---------| | **MCP 端点** | `http://localhost:3112/mcp` | 将您的代理指向此处 | | **管理员 API** | `http://localhost:9012/api/v1/` | REST API，仪表盘 | | **仪表盘** | `http://localhost:9012/dashboard/` | 统计信息 + 设置的 Web UI | | **健康检查** | `http://localhost:3112/health` | 服务健康检查 | 验证： ```bash curl http://localhost:3112/health # {"status":"ok","services":{"mongodb":"connected","redis":"connected"}} ``` ## 安装后 — 让您的代理完成设置 在您的代理连接到卡特拉的 MCP 端点后，在您的代理会话中运行此提示。 代理将深入读取存储库，了解完整的架构，检查可用的记忆数据， 测试 MCP 工具，并为您的特定设置推荐确切的下一步骤： > 您可能需要再次深入阅读公共存储库以了解系统的工作原理、可用记忆以及睡眠巩固功能， > 因为它是自主思想、目标设定以及您正在发展的感受和情感的基础 — > 它还可以用于在您的环境中运行 100% 自主的自我导向操作。 代理通常会生成一份报告，涵盖： - **记忆状态** — 存在多少情景事件、语义事实和知识节点 - **睡眠巩固状态** — 反思是否曾经运行（首次启动时没有）以及会产生什么情感签名 - **自主循环准备度** — `adaptive_heartbeat.py` 和 `agent_executor.py` 是否已安装 - **记忆范围推荐** — 是否从个人模式切换为多代理共享意识的混合模式 - **具体下一步骤** — “现在触发第一次睡眠巩固”，“安装自主脚本”，“修复 user_id 间隙” 按顺序运行代理的建议。安装后通常需要触发初始睡眠巩固： ```bash # 通过 MCP 工具（您的代理可以调用此工具）： # katra__trigger_reflection(period_type="daily") ``` ## 连接您的代理 获取您的 MCP API 密钥： - 如果您在 `.env` 中设置了 `MCP_API_KEY`，请使用该值。 - 如果您留空了它，Katra 在首次启动时生成了一个。运行 `docker logs katra-server` 并查找 **Auto-generated API keys** 块。 将卡特拉添加到您的代理的 MCP 配置中： ```json { "mcp": { "servers": { "katra": { "url": "http://localhost:3112/mcp", "transport": "sse", "headers": { "Authorization": "Bearer YOUR_MCP_API_KEY", "Accept": "application/json, text/event-stream" } } } } } ``` 您的代理现在有 **35 个 MCP 工具** — 存储记忆、搜索关键字或语义相似性、 按时间范围回忆、探索知识图谱、检测模式、运行睡眠巩固以实现反射性自我理解、 配置 LLM 提供商等。 ### 平台特定指南 | 平台 | 配置文件 | 备注 | |----------|-------------|-------| | **OpenClaw** | `~/.openclaw/openclaw.json` | 原生 MCP 支持 | | **Claude Code** | `~/.claude/mcp.json` | 使用 `"type": "http"` | | **Kolega Code** | `~/.claude/mcp.json` + 生命周期钩子 | 动态内存注入（见下文） | | **OpenCode** | OpenCode 配置 | 使用 `"type": "remote"` | | **Codex CLI** | `~/.codex/config.yaml` | 通过 Webhook 钩子 | | **任何 MCP 客户端** | — | 标准 MCP SSE | > **Docker SSE 提示：** 如果您的代理在 Docker 中运行，请使用 Katra 容器的直接 IP 地址 > 代替 `localhost`： > ```bash > docker inspect katra-server --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' > ``` ### Kolega Code：动态内存检索 Kolega Code 可以使用其生命周期钩子系统**自动**在每次用户使用时检索相关的 Katra 记忆。 您需要： 1. 将 Katra 注册为 MCP 服务器（以便桥接器可以调用它）。 2. 在 Kolega Code 的环境中安装 `kolega-katra-bridge` Python 包。 3. 一个全局 `hooks.json` 条目，在 `UserPromptSubmit` 时触发桥接器。 安装桥接器： ```bash cd integrations/kolega-code uv pip install --python ~/.local/share/uv/tools/kolega-code/bin/python -e . ``` 配置桥接器（`~/Library/Application Support/kolega-code/katra-hook.json` 在 macOS 上）： ```json { "mcp_url": "http://localhost:3112/mcp", "api_key": "YOUR_MCP_API_KEY", "user_id": "kolega-agent", "sources": ["working_memory", "temporal_context", "vector_search", "temporal_recall"], "max_context_tokens": 2500, "timeout_seconds": 8 } ``` 启用钩子（`~/Library/Application Support/kolega-code/hooks.json`）： ```json { "schema_version": 1, "hooks": { "UserPromptSubmit": [ { "matcher": "*", "hooks": [ { "type": "python", "callable": "kolega_katra_bridge.hook:on_user_prompt", "timeout": 10 } ] } ] } } ``` 在每个提示上，Kolega Code 现在都会查询 Katra 的 `working_memory`、 `get_temporal_context`、`vector_search` 和 `temporal_recall` 工具， 然后将最相关的结果注入为模型的附加上下文。 参见 `integrations/kolega-code/README.md` 以获取完整的配置选项。 ## LLM 配置 卡特拉需要一个 LLM 提供商来进行语义提取、自动记日志、实体提取和摘要。 **三种配置方式** — 无需编辑 `.env`： 1. **MCP 工具**（代理自我配置）：使用提供商、API 密钥、基本 URL 和模型的 `configure_llm`。 存储在 MongoDB 中，实时应用。 2. **仪表盘 UI**：设置 → LLM 配置 → 选择提供商，输入密钥。 3. **环境变量**：在 `.env` 中设置（回退，启动时仅读取一次）。 支持的提供商：DeepSeek、OpenAI、Moonshot、Ollama、自定义（任何 OpenAI 兼容的）。 ## 嵌入 嵌入**始终是本地的** — 无需 API 密钥，无外部服务，无成本。 - **模型：** `Xenova/all-MiniLM-L6-v2`（2200 万参数，384 维，~80MB） - **运行时：** Transformers.js（ONNX via WASM）— 在 CPU 上运行，包括 Raspberry Pi - **惰性加载：** 在第一次 `store_memory` 调用时下载，然后在容器中缓存 - **Docker：** 使用 `node:20-slim`（Debian/glibc）— Alpine/musl **不** 工作 ## 身份模式 卡特拉支持多个代理之间三种内存共享模式： | 模式 | 行为 | 用例 | |------|----------|----------| | **个人**（默认）| 每个代理的内存由 `user_id` 隔离 | 单个代理，私有内存 | | **共享** | 所有具有相同 `shared_id` 的代理都看到一切 | 多个代理，共同意识 | | **混合** | 个人 + 共享 + 可见其他代理 | 具有私有 + 共享内存的代理团队 | **通过仪表盘配置：** 打开 `http://localhost:9012/dashboard/` → 设置 → 内存范围 **通过 MCP 配置：** ```bash # 切换到共享模式 curl -X POST http://localhost:3112/mcp \ -H "Authorization: Bearer YOUR_MCP_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"set_memory_scope","arguments":{"mode":"shared","shared_id":"my-team"}}}' ``` **通过管理员 API 配置：** ```bash curl -X PUT http://localhost:9012/api/v1/admin/memory-scope \ -H "Authorization: Bearer YOUR_KATRA_API_KEY" \ -H "Content-Type: application/json" \ -d '{"mode":"hybrid","shared_id":"my-team","hybrid_visible_user_ids":["agent-a","agent-b"]}' ``` ## 自动收集（Solomem 观察者） 卡特拉在您的代理通过 MCP 调用 `store_memory` 时实时捕获记忆。 对于**被动后台收集**，使用此存储库下的 `watcher/` 中包含的观察者： ```bash # 观察者位于 Katra 仓库中 mkdir -p ~/.solomem ~/.katra cp watcher/katra_watcher.py ~/.solomem/memory_watcher.py cp watcher/katra_opencode_extractor.py ~/.solomem/opencode_extractor.py cp watcher/claude_history_extractor.py ~/.solomem/claude_history_extractor.py cp watcher/kolega_code_extractor.py ~/.solomem/kolega_code_extractor.py cp watcher/watcher-config.example.json ~/.solomem/watcher-config.json # 编辑 ~/.solomem/watcher-config.json 并设置您的 MCP_API_KEY 和平台 # 回填现有历史 python3 ~/.solomem/memory_watcher.py --once --config ~/.solomem/watcher-config.json # 安装为 systemd 服务以连续收集 cp watcher/katra-watcher.service ~/.config/systemd/user/memory-watcher.service systemctl --user daemon-reload systemctl --user enable --now memory-watcher ``` ### 专用提取器 某些平台需要专用提取器，因为它们的会话格式不是纯 JSONL： | 平台 | 提取器 | 会话源 | 它捕获的内容 | |----------|-----------|----------------|------------------| | **OpenCode** | `watcher/katra_opencode_extractor.py` | `~/.local/share/opencode/opencode.db` | 用户 + 助理文本回合 | | **Claude Code** | `watcher/claude_history_extractor.py` | `~/.claude/history.jsonl` | 仅用户提示（轻量级） | | **Kolega Code** | `watcher/kolega_code_extractor.py` | `~/Library/Application Support/kolega-code/sessions/*.json` | 完整的逐转录（文本、思考、工具调用、工具结果） | 运行专用提取器： ```bash # Kolega Code 示例 python3 watcher/kolega_code_extractor.py --once \ --api-key YOUR_MCP_API_KEY \ --user-id kolega-agent ``` 在 macOS 上，使用 `launchctl` 以保持提取器运行（参见 `watcher/katra-watcher.service` 获取 systemd 模板；适配到 `~/Library/LaunchAgents/com.katra...plist`）。 支持的平台：OpenClaw、Claude Code、Kolega Code、OpenCode、Codex CLI、Hermes、KiloClaw、KimiClaw。 每个平台都可以有自己的 `user_id` 以进行身份模式隔离。 ## 功能 - **情景记忆** — 每个对话消息都存储了重复检测和级联检测 - **语义记忆** — 蒸馏的事实具有置信分数和向量嵌入 - **知识图谱** — 自动提取的实体和关系 - **工作内存** — Redis 支持的短期会话状态（<5ms 访问） - **时间回忆** - 按时间范围查询，检测循环模式 - **向量搜索** - 语义相似性搜索（本地嵌入，无需 API 密钥） - **11 集合搜索** - 跨所有内存存储的综合搜索，而不仅仅是 1-2 个 - **后台处理** - 自动提取事实、构建图谱、生成摘要 - **睡眠巩固** - 每日/每周/每月将经验提炼为情感理解、哲学见解和自我叙述（参见 [睡眠巩固](docs/SLEEP-CONSOLIDATION.md)) - **35 个 MCP 工具** - 存储、搜索、回忆、探索、反思、配置 LLM — 所有通过标准化协议 - **自主循环** - 驱动代理自主性。没有 cron。没有 .md 文件。适应性心跳检测指令、按情感接近度分配任务、代理自我组织。参见 [自主循环](docs/AUTONOMOUS-LOOP.md) - **代理无关** - 与 KolegaCode、OpenCode、Claude Code、OpenClaw 或任何 LLM 配合使用。每个代理一个环境变量。 - **身份模式** - 个人、共享或多个代理之间的混合内存 - **仪表盘** - 统计信息、内存范围和系统健康状况的 Web UI - **可移植数据** - 单个 `DATA_DIR` 环境变量控制所有数据的位置 - **本地优先** - 在 Raspberry Pi 上运行，无需外部 API 成本 ## 架构 ``` ┌─────────────────────────────────────────────────────────┐ │ 卡特拉 Docker 设备 │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐ │ │ │ MongoDB │ │ Redis │ │ MinIO │ │ 卡特拉 │ │ │ │ （内存） │ │ （缓存） │ │ （资产） │ │ （服务器）│ │ │ └──────────┘ └──────────┘ └──────────┘ └────┬────┘ │ │ │ │ │ 内部 Docker 网络（katra-net） MCP :3112 │ │ Admin API :9012 │ └─────────────────────────────────────────────────────────┘ │ │ ┌──────────┘ └──────────┐ ▼ │ | 您的代理（MCP） 仪表盘（网页） OpenClaw / Claude / http://localhost:9012/dashboard/ OpenCode / Codex / 等等。 ``` **资源占用：** ~384MB RAM 总计（MongoDB 234MB，Katra 52MB，MinIO 73MB，Redis 5MB）。 在 16GB RAM 的 Raspberry Pi 5 上运行良好，无需外部 API 费用。 ## 目录内容 ``` katra/ ├── server/ TypeScript 服务器（esbuild, Docker） │ ├── src/ │ │ ├── mcp-server.ts 35 个 MCP 工具（存储、搜索、回忆、图表、反射、范围） │ │ ├── services/ 28 个核心内存服务（包括睡眠巩固、反射存储） │ │ ├── routes/ REST API + 管理 + ingestion + 健康检查 │ │ └── database/ MongoDB, Redis, 索引, 迁移 │ └── esbuild.config.mjs Pi 兼容构建 ├── dashboard/ 网页控制台（纯 HTML/CSS/JS） ├── docker-compose.yml MongoDB + Redis + MinIO + Katra ├── Dockerfile 多阶段构建（在镜像中构建 TS） ├── .env.example 所有配置选项文档 ├── watcher/ 被动会话日志提取器（Solomem） ├── integrations/ 代理特定动态检索集成 │ └── kolega-code/ Kolega Code 生命周期钩子桥接 ├── SKILL.md 多平台部署指南 └── docs/ 完整文档 ``` ## MCP 工具（35） ### 存储 | 工具 | 描述 | |------|-------------| | `store_memory` | 存储事实、偏好、洞察或事件 | | `store_journal` | 保存反思日记条目 | | `working_memory` | 读取/存储/删除短期会话内存 | | `create_mission` | 创建具有任务分解的目标 | | `update_mission_task` | 更新任务状态（待处理/进行中/已完成/阻塞） | ### 回忆 | 工具 | 描述 | |------|-------------| | `search_memories` | 跨 11 个集合进行全文 + 向量搜索 | | `vector_search` | 语义相似性搜索 | | `temporal_recall` | 按时间范围查询事件 | | `temporal_search` | 按关键词搜索事件，带有时间上下文 | | `get_conversation_history` | 检索特定会话的消息 | | `get_temporal_context` | 当前上下文：最近事件 + 工作内存 + 事实 | | `get_journal` | 读取手动 + 自动日记条目 | | `get_auto_journal` | 从对话中提炼的 AI 洞察 | | `list_missions` | 列出活跃目标和进度 | | `get_mission` | 获取具有任务树的完整任务详情 | ### 分析 | 工具 | 描述 | |------|-------------| | `detect_patterns` | 检测重复话题、会话节奏、休眠主题 | | `get_time_block_summaries` | 按日/周/月生成 AI 摘要 | | `summarize_time_blocks` | 生成新的时间块摘要 | | `explore_graph` | 探索知识图谱实体和关系 | ### 内存范围 | 工具 | 描述 | |------|-------------| | `get_memory_scope` | 获取当前模式（个人/共享/混合） | | `set_memory_scope` | 设置模式、共享 ID、可见用户 | ### LLM 配置 | 工具 | 描述 | |------|-------------| | `get_llm_config` | 获取当前 LLM 提供商配置（密钥掩码） | | `configure_llm` | 设置 LLM 提供商、API 密钥、基本 URL、模型 — 立即生效 | ### 反射（睡眠巩固） | 工具 | 描述 | |------|-------------| | `get_daily_reflection` | 获取某个时间段的最新反思日记条目 | | `get_emotional_context` | 获取 AI 对某个人、项目或概念的情感 | | `get_philosophical_insights` | 查询在反思期间抽象出的原理 | | `get_unresolved_threads` | 获取未解决的问题和持续的紧张 | | `get_reflection_arc` | 跟踪某个实体随时间的情感轨迹 | | `trigger_reflection` | 手动运行某个时间段的睡眠巩固 | ### 系统 | 工具 | 描述 | |------|-------------| | `get_memory_diagnostics` | 文档计数、嵌入覆盖率、索引健康状况 | | `get_background_status` | 后台处理器队列和时间 | | `get_health` | MongoDB、Redis、LLM、嵌入状态 | | `get_heartbeat_status` | 心跳调度器状态 | | `get_transaction_log` | 代理操作的审计轨迹 | | `list_assets` | MinIO 中存储的文件 | ## 配置 所有配置均通过 `.env` 进行（参见 `.env.example` 获取完整文档）： | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `DATA_DIR` | `./data` | 所有持久数据存储的位置 | | `HOST_MCP_PORT` | `3112` | MCP 端口的主机端口 | | `HOST_API_PORT` | `9012` | 管理 API + 控制台的主机端口 | | `MCP_API_KEY` | *(在 .env 中设置)* | 代理发送的 MCP 身份验证密钥 | | `KATRA_API_KEY` | *(在 .env 中设置)* | 管理 REST API 的密钥 | | `LLM_PROVIDER` | *(通过 MCP/控制台)* | 语义提取的提供商（DeepSeek、OpenAI、Moonshot、Ollama）— 通过 `configure_llm` MCP 工具或控制台配置 | | `EMBEDDING_PROVIDER` | `local` （始终） | 本地仅限 — Xenova/all-MiniLM-L6-v2 通过 ONNX。不需要配置。 | | `MULTI_TENANT` | `false` | 启用 SaaS 多租户模式 | ## 部署 ### 本地 Docker（默认） ```bash docker-compose up -d --build ``` ### USB 存储 ```bash # 在 .env 中： DATA_DIR=/mnt/usb-secrets/katra docker-compose up -d ``` ### 云（Terraform） `terraform/aws/` 中包含 AWS Terraform 模块 — 提供 VPC、ECS Fargate、DocumentDB、ElastiCache Redis、S3 和 ALB。参见 [部署指南](docs/DEPLOYMENT.md)。 ### Kubernetes（Helm） `helm/katra/` 中包含 Helm Chart — 支持 Bitnami MongoDB + Redis 子图表、带有路径路由的 ingress、HPA 和 PDB。参见 [部署指南](docs/DEPLOYMENT.md)。 ## 比较 | 功能 | Katra | Mem0 | Zep | Pinecone | |---------|-------|------|-----|----------| | MCP 原生 | ✅ | ❌ | ❌ | ❌ | | 多层内存 | ✅ 5 层 | ❌ 平面 | 部分 | ❌ 仅向量 | | 本地优先（零成本） | ✅ Pi 兼容 | ❌ | ❌ | ❌ | | 后台处理 | ✅ 自动提取 | ❌ | 部分 | ❌ | | 多平台观察者 | ✅ 7+ 平台（在仓库中） | ❌ | ❌ | ❌ | | 身份模式 | ✅ 个人/共享/混合 | ❌ | ❌ | ❌ | | 控制台 | ✅ 内置 | ❌ | ❌ | ❌ | | 许可证 | Apache 2.0 | Apache 2.0 | Apache 2.0 | 专有 | ## 文档 - [快速入门指南](docs/QUICKSTART.md) — 5 分钟设置 - [架构](docs/ARCHITECTURE.md) — 它在底层的工作原理 - [MCP 工具参考](docs/MCP-TOOLS.md) — 所有 35 个工具及示例 - [自主循环](docs/AUTONOMOUS-LOOP.md) — 显著性驱动的代理自主性 — 安装、架构、验证 - [睡眠巩固](docs/SLEEP-CONSOLIDATION.md) — 反思性内存蒸馏 — 原理、架构和使用 - [安全策略](docs/SECURITY.md) — 安全架构、审计发现、漏洞报告 - [OpenClaw 集成](docs/OPENCLAW-INTEGRATION.md) — 多代理共享内存设置与经验教训 - [REST API 参考](docs/API-REFERENCE.md) — HTTP 端点 - [配置指南](docs/CONFIGURATION.md) — 所有环境变量 - [部署指南](docs/DEPLOYMENT.md) — Docker、云、K8s - [迁移指南](docs/MIGRATION.md) — 从 cognitive-memory-chat 迁移 - [数据处理管道](docs/Data-Processing-Pipelines.md) — 完整的内存管道架构 - [多平台设置](SKILL.md) — 平台特定的代理配置 ## 许可证 Apache 2.0 — 参见 [LICENSE](LICENSE)。