[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80986":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":13,"stars7d":15,"stars30d":16,"stars90d":14,"forks30d":14,"starsTrendScore":17,"compositeScore":18,"rankGlobal":9,"rankLanguage":9,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":9,"pushedAt":9,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":14,"starSnapshotCount":14,"syncStatus":27,"lastSyncTime":28,"discoverSource":29},80986,"mempalace-evolve","a2328275243\u002Fmempalace-evolve","a2328275243","Self-evolving memory palace for AI agents — persistent memory with automatic learning, knowledge graph, and multi-agent support",null,"Python",170,8,5,0,25,128,16,75.36,"MIT License",false,"master",true,[],"2026-06-12 04:01:31","\u003C!--\n╔══════════════════════════════════════════════════════════════════════╗\n║  DreamSeed 种梦计划 — AI创造者大赛  官方 README 模板                ║\n║                                                                      ║\n║  使用说明：                                                          ║\n║  1. 将本模板放在参赛仓库根目录 README.md 的顶部                       ║\n║  2. 头图使用 DreamField 官方公开活动图片地址                         ║\n║  3. 请保留 DREAMFIELD_README_HEADER_START \u002F END 标识                 ║\n║  4. 分割线以下供创作者自由编写项目内容                               ║\n╚══════════════════════════════════════════════════════════════════════╝\n-->\n\n\u003C!-- DREAMFIELD_README_HEADER_START -->\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fwww.dreamfield.top\">\n    \u003Cimg src=\"https:\u002F\u002Fwww.dreamfield.top\u002Fdream-field\u002Fcontest-readme\u002Fassets\u002Fdreamseed-readme-banner.png\" alt=\"DreamSeed 种梦计划参赛作品\" width=\"100%\" \u002F>\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003C!-- DREAMFIELD_README_HEADER_END -->\n\n---\n\n# mempalace-evolve\n\n[![Python 3.10+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.10%2B-blue)](https:\u002F\u002Fwww.python.org\u002F)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-green)](LICENSE)\n[![Tests](https:\u002F\u002Fgithub.com\u002Fa2328275243\u002Fmempalace-evolve\u002Factions\u002Fworkflows\u002Ftests.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fa2328275243\u002Fmempalace-evolve\u002Factions\u002Fworkflows\u002Ftests.yml)\n\n**给 AI Agent 用的自进化记忆系统。**\n\nAgent 跑完一轮对话就什么都忘了？这个项目让你的 Agent 拥有持久记忆——不只是存起来，还会自己筛选、打分、淘汰，越用越聪明。\n\n不绑定任何框架。OpenAI、Claude、LangChain、自己写的 Agent，都能接。\n\n## 目录\n\n- [安装](#安装)\n- [30 秒体验](#30-秒体验)\n- [模式 A：MCP 配置（零代码）](#模式-amcp-配置指南详细)\n- [模式 B：Python SDK](#模式-bpython-sdk-完整指南)\n- [自进化原理](#自进化原理核心特色)\n- [自动 \u002F 手动 \u002F 可配置自动](#自动--手动--可配置自动)\n- [记忆类型系统](#记忆类型系统认知科学三分法)\n- [高级功能](#高级功能)\n  - [可配置评分规则](#可配置评分规则)\n  - [混合检索（向量 + 知识图谱）](#混合检索向量--知识图谱扩展)\n  - [增量进化](#增量进化)\n  - [跨项目经验自动共享](#跨项目经验自动共享)\n  - [Working Memory 缓存](#working-memory-缓存)\n  - [智能晋升机制](#智能晋升机制)\n- [完整 API 参考](#完整-api-参考)\n- [CLI 命令](#cli-命令)\n\n---\n\n## 为什么需要这个？\n\n| 问题 | mempalace-evolve 的解决方案 |\n|------|---------------------------|\n| AI 跨会话失忆 | 持久化记忆 + 语义检索，下次对话自动召回相关上下文 |\n| 记忆越存越多越乱 | 自进化：自动去重、合并相似、淘汰过时、晋升高质量 |\n| 存了但找不到 | 向量语义搜索 + 知识图谱双通道检索 |\n| 接入成本高 | 3 行代码接入，支持 MCP\u002FOpenAI\u002FLangChain\u002FREST |\n\n## 安装\n\n```bash\n# 从 GitHub 安装（推荐）\npip install git+https:\u002F\u002Fgithub.com\u002Fa2328275243\u002Fmempalace-evolve.git\n\n# 需要 MCP 支持（Claude Code \u002F Cursor）\npip install \"mempalace-evolve[mcp] @ git+https:\u002F\u002Fgithub.com\u002Fa2328275243\u002Fmempalace-evolve.git\"\n\n# 需要 REST API\npip install \"mempalace-evolve[api] @ git+https:\u002F\u002Fgithub.com\u002Fa2328275243\u002Fmempalace-evolve.git\"\n```\n\n要求：Python >= 3.10 | 核心依赖仅 `chromadb` 一个包 | 不需要 GPU，全部本地运行\n\n## 30 秒体验\n\n安装后直接运行，不需要写任何代码：\n\n```bash\n# 验证安装是否正常\npython -m mempalace_evolve.cli doctor\n\n# 一键演示全部功能（存储 → 搜索 → 知识图谱 → 自进化）\npython -m mempalace_evolve.cli demo\n\n# 交互式体验（输入文字自动存储，\u002Fsearch 搜索）\npython -m mempalace_evolve.cli playground\n```\n\n---\n\n## 快速上手：两种使用模式\n\n### 模式 A：MCP 协议（AI 自动存取，零代码）\n\n适用于 Claude Code、Cursor 等支持 MCP 的 AI 工具。配置后 AI 自动获得记忆能力，**不需要写任何代码**。\n\n### 模式 B：Python SDK（手动集成到你的 AI 应用）\n\n适用于自建 Agent、OpenAI API 应用、LangChain 项目等。通过代码调用 SDK 接口。\n\n---\n\n## 模式 A：MCP 配置指南（详细）\n\nMCP（Model Context Protocol）让 AI 自动拥有记忆工具。配置一次，之后 AI 会自己决定什么时候存、什么时候搜。\n\n### 第一步：安装\n\n```bash\npip install \"mempalace-evolve[mcp] @ git+https:\u002F\u002Fgithub.com\u002Fa2328275243\u002Fmempalace-evolve.git\"\n```\n\n### 第二步：一键配置（推荐）\n\n安装后运行交互式向导，自动检测环境、写入配置：\n\n```bash\nmempalace setup\n```\n\n向导会自动完成：\n1. 检测 Python \u002F chromadb \u002F fastmcp 是否安装\n2. 检测 Claude Code \u002F Cursor 配置目录\n3. 收集 wing 名称和存储路径\n4. 写入 MCP 配置（自动备份旧配置）\n5. 验证 MCP Server 能正常启动\n\n也可以跳过交互，直接指定参数：\n\n```bash\nmempalace setup --wing my_project --palace ~\u002F.mempalace\n```\n\n### 手动配置（备选）\n\n如果向导不适合你的环境，可以手动编辑配置文件：\n\n**Claude Code** — 编辑 `~\u002F.claude\u002Fsettings.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"mempalace\": {\n      \"command\": \"mempalace-mcp\",\n      \"env\": {\n        \"MEMPALACE_PATH\": \"绝对路径\u002F.mempalace\",\n        \"MEMPALACE_WING\": \"my_project\"\n      }\n    }\n  }\n}\n```\n\n> ⚠️ 注意：`MEMPALACE_PATH` 必须用绝对路径，`~` 在 JSON 配置中不会被展开。\n\n**Cursor** — 在 Settings → MCP Servers 中添加（同样用绝对路径）：\n\n```json\n{\n  \"mempalace\": {\n    \"command\": \"mempalace-mcp\",\n    \"env\": {\n      \"MEMPALACE_PATH\": \"绝对路径\u002F.mempalace\",\n      \"MEMPALACE_WING\": \"my_project\"\n    }\n  }\n}\n```\n\n> 如果 `mempalace-mcp` 命令找不到，改用：`\"command\": \"python\", \"args\": [\"-m\", \"mempalace_evolve.adapters.mcp_server\"]`\n\n### 第三步：重启 AI 工具\n\n重启后，AI 自动获得 6 个记忆工具：\n\n| 工具 | 作用 |\n|------|------|\n| `remember` | 存储一条记忆到指定 room |\n| `recall` | 语义搜索相关记忆 |\n| `add_fact` | 添加知识图谱三元组 |\n| `query_entity` | 查询实体关系 |\n| `forget` | 删除指定记忆 |\n| `evolve` | 触发一次自进化（清理 + 晋升 + 合并） |\n\n### 配置参数说明\n\n| 环境变量 | 说明 | 默认值 |\n|----------|------|--------|\n| `MEMPALACE_PATH` | 记忆存储目录 | `~\u002F.mempalace` |\n| `MEMPALACE_WING` | 项目\u002F翼名称（隔离不同项目的记忆） | `global` |\n\n**多项目配置示例：**\n\n```json\n{\n  \"mcpServers\": {\n    \"mempalace-web\": {\n      \"command\": \"mempalace-mcp\",\n      \"env\": { \"MEMPALACE_PATH\": \"C:\u002FUsers\u002F你的用户名\u002F.mempalace\", \"MEMPALACE_WING\": \"web_app\" }\n    },\n    \"mempalace-ml\": {\n      \"command\": \"mempalace-mcp\",\n      \"env\": { \"MEMPALACE_PATH\": \"C:\u002FUsers\u002F你的用户名\u002F.mempalace\", \"MEMPALACE_WING\": \"ml_project\" }\n    }\n  }\n}\n```\n\n每个 wing 的 semantic\u002Fepisodic 记忆相互隔离。procedural 记忆（错误模式、经验教训）自动在所有 wing 间共享。\n\n---\n\n## 模式 B：Python SDK 完整指南\n\n适用于自建 AI 应用、没有 MCP 的场景。\n\n### 基础用法\n\n```python\nfrom mempalace_evolve import MemPalace\n\npalace = MemPalace(\".\u002Fmy-project-memory\", wing=\"my_project\")\n\n# 存记忆（指定 room 分类）\npalace.remember(\"数据库用 PostgreSQL，ORM 用 SQLAlchemy\", room=\"decisions\")\npalace.remember(\"CORS 问题通过添加中间件解决\", room=\"errors\")\n\n# 语义搜索（不需要精确匹配关键词）\nresults = palace.recall(\"用了什么数据库\")\nprint(results[0][\"content\"])\n# → \"数据库用 PostgreSQL，ORM 用 SQLAlchemy\"\n\n# 知识图谱\npalace.add_fact(\"项目\", \"使用\", \"PostgreSQL\")\npalace.add_fact(\"API\", \"框架\", \"FastAPI\")\nrels = palace.query_entity(\"项目\")\n```\n\n### 对话记忆：digest() + context_for()\n\n这是最核心的 API——让你的 AI 应用拥有跨会话记忆：\n\n```python\nfrom mempalace_evolve import MemPalace\n\npalace = MemPalace(\".\u002Fagent-memory\", wing=\"my_agent\")\n\n# ═══ 对话结束时：自动提取知识 ═══\npalace.digest([\n    {\"role\": \"user\", \"content\": \"我们决定用 Redis 做缓存，TTL 设 1 小时\"},\n    {\"role\": \"assistant\", \"content\": \"好的，已配置 Redis，TTL=3600s\"},\n    {\"role\": \"user\", \"content\": \"认证用 JWT，别用 session\"},\n])\n# 自动提取关键信息存入记忆，不需要手动指定存什么\n\n# ═══ 下次对话开始时：注入相关上下文 ═══\ncontext = palace.context_for(\"缓存怎么配置的？\")\n# 返回: \"- [decisions] 我们决定用 Redis 做缓存，TTL 设 1 小时...\"\n\n# 把 context 注入到 system prompt\nsystem_prompt = f\"\"\"你是一个编程助手。以下是之前对话中的相关记忆：\n{context}\n\n请基于这些上下文回答用户问题。\"\"\"\n```\n\n### 完整集成示例（OpenAI API）\n\n```python\nimport openai\nfrom mempalace_evolve import MemPalace\n\npalace = MemPalace(\".\u002Fmy-app-memory\", wing=\"chatbot\")\n\ndef chat(user_message: str, history: list) -> str:\n    # 1. 检索相关记忆作为上下文\n    context = palace.context_for(user_message)\n\n    # 2. 构建 prompt\n    system = \"你是一个助手。\"\n    if context:\n        system += f\"\\n\\n已知信息（来自之前的对话）:\\n{context}\"\n\n    messages = [{\"role\": \"system\", \"content\": system}] + history\n    messages.append({\"role\": \"user\", \"content\": user_message})\n\n    # 3. 调用 LLM\n    response = openai.chat.completions.create(\n        model=\"gpt-4\", messages=messages\n    )\n    reply = response.choices[0].message.content\n\n    # 4. 对话结束后提取记忆\n    history.append({\"role\": \"user\", \"content\": user_message})\n    history.append({\"role\": \"assistant\", \"content\": reply})\n    palace.digest(history)\n\n    return reply\n```\n\n### 自进化：evolve()\n\n每次调用 `evolve()` 会自动执行完整的记忆维护：\n\n```python\nreport = palace.evolve(transcript=\"今天的对话内容...\")\n# report 包含：\n# - candidates: 提取了多少候选记忆\n# - promoted: 晋升了多少条\n# - merged: 合并了多少重复\n# - opportunistic: 4 项被动维护结果\n```\n\n---\n\n## 自进化原理（核心特色）\n\n这是 mempalace-evolve 区别于普通向量数据库的核心能力。记忆不是存了就不管，系统会**自动维护记忆质量**：\n\n### 主动进化（evolve 时触发）\n\n```\n对话结束 → CandidateExtractor 扫描全文\n  ↓\n关键词匹配 + 内容评分 → 生成候选 (0-10 分)\n  ↓\nMemoryReviewer 评审:\n  score >= 7 → 晋升为长期记忆\n  score \u003C  3 → 丢弃\n  中间地带   → 等待观察\n  ↓\n晋升的记忆 → ChromaDB 向量库 → 下次对话自动语义召回\n```\n\n### 被动进化（4 项自动维护机制）\n\n每次 `evolve()` 还会执行 4 项后台维护：\n\n| 机制 | 作用 | 触发条件 |\n|------|------|----------|\n| **低分清理** | 删除评分低且长期未访问的记忆 | 评分 \u003C 0.3 且 90 天未访问 |\n| **候选晋升** | 高质量候选记忆自动晋升为正式记忆 | 候选评分 >= 0.45 |\n| **孤立实体清理** | 删除知识图谱中无关系的孤立节点 | 实体无任何出入关系 |\n| **过时决策标记** | 标记长期未更新的决策为 stale | 180 天未访问的 decisions |\n\n### 反馈回路\n\n每次 `recall()` 搜索记忆时，被召回的记忆会自动更新 `last_accessed` 时间戳。经常被用到的记忆不会被清理，长期不用的会逐渐淘汰。**越用越精准，不用的自动消失。**\n\n### 合并去重\n\n存入相似内容时自动检测重复，合并为一条更完整的记忆，避免信息冗余。\n\n---\n\n## 自动 \u002F 手动 \u002F 可配置自动\n\n### 完全自动（不需要你做任何事）\n\n- **反馈回路**：每次 `recall()` 搜索时，被命中的记忆自动刷新活跃度。常用的不会被清理，不用的逐渐淘汰。\n- **合并去重**：evolve 执行时自动检测相似记忆并合并。\n- **低分清理**：评分 \u003C 0.3 且 90 天没被访问的记忆自动删除。\n- **候选晋升**：候选区中评分 >= 0.45 的记忆自动晋升为正式记忆。\n- **孤立实体清理**：知识图谱中没有任何关系的孤立节点自动删除。\n- **过时决策标记**：decisions room 中 180 天没更新的自动标记为 stale。\n\n以上全部在 `evolve()` 被调用时自动执行，不需要额外配置。\n\n### 需要触发的（一次调用，全部执行）\n\n`evolve()` 本身需要被触发。触发一次 = 上面 6 项全部执行。\n\n### 存储记忆\n\n| 模式 | 谁来存 |\n|------|--------|\n| MCP（Claude Code \u002F Cursor） | AI 自己判断什么值得存，自动调用 remember 工具 |\n| SDK（自建应用） | 你的代码调 `palace.remember()` 或 `palace.digest()` |\n| REST | 你的代码 POST \u002Fremember |\n\n### 如何让 evolve 也变成自动的\n\n**MCP 模式 — 方法 1：告诉 AI 去做**\n\n在项目 `CLAUDE.md` 或 system prompt 里加：\n\n```\n对话结束前调用 evolve 工具。\n```\n\nAI 看到这句话就会在每次对话结束时自动触发进化。\n\n**MCP 模式 — 方法 2：配 hook（完全无感）**\n\nClaude Code 支持 hook，对话结束时自动执行命令：\n\n```json\n{\n  \"hooks\": {\n    \"PostToolUse\": [{\n      \"matcher\": \"stop\",\n      \"command\": \"python -c \\\"from mempalace_evolve import MemPalace; MemPalace('~\u002F.mempalace').evolve()\\\"\"\n    }]\n  }\n}\n```\n\n放在 `.claude\u002Fsettings.json` 里，之后每次对话结束自动进化，AI 和用户都不需要操心。\n\n**SDK 模式 — 对话结束时调一行**\n\n```python\ndef on_session_end(messages):\n    palace.digest(messages)  # 提取知识\n    palace.evolve()          # 进化\n```\n\n**SDK 模式 — 内置自动进化（最简单）**\n\n```python\n# auto_evolve=True 自动启动后台线程，每小时 evolve 一次\npalace = MemPalace(\".\u002Fmemory\", auto_evolve=True, evolve_interval=3600)\n# 之后正常使用即可，不需要手动调 evolve()\n```\n\n**SDK 模式 — 定时任务**\n\n```python\nimport schedule\nschedule.every(1).hours.do(lambda: palace.evolve())\n```\n\n**REST 模式 — cron**\n\n```bash\n0 2 * * * curl -X POST http:\u002F\u002Flocalhost:8765\u002Fevolve\n```\n\n### 各模式总览\n\n| 模式 | 存记忆 | 搜记忆 | 进化 | 全自动方案 |\n|------|--------|--------|------|-----------|\n| MCP | AI 自动 | AI 自动 | AI 调工具 | 加一句 prompt 或配 hook |\n| SDK | `remember()` \u002F `digest()` | `recall()` \u002F `context_for()` | `evolve()` | 放在 session end 回调里 |\n| REST | POST \u002Fremember | POST \u002Frecall | POST \u002Fevolve | cron 定时 |\n\n---\n\n## 其他适配器\n\n### OpenAI Function Calling\n\n```python\nfrom mempalace_evolve import MemPalace\nfrom mempalace_evolve.adapters.openai_adapter import OpenAIAdapter\n\npalace = MemPalace(\".\u002Fmemory\")\nadapter = OpenAIAdapter(palace)\n\n# 获取 tools 定义，传给 OpenAI API\ntools = adapter.get_tools()\n\n# 处理 LLM 返回的 tool call\nresult = adapter.handle_tool_call(tool_name, arguments)\n```\n\n### LangChain\n\n```python\nfrom mempalace_evolve import MemPalace\nfrom mempalace_evolve.adapters.langchain_adapter import LangChainAdapter\n\npalace = MemPalace(\".\u002Fmemory\")\nadapter = LangChainAdapter(palace)\ntools = adapter.get_tools()  # 返回 StructuredTool 列表，直接接入 agent\n```\n\n### REST API\n\n```bash\n# 启动 HTTP 服务\npython -m mempalace_evolve.cli serve --port 8765\n\n# 带 API key 认证\npython -m mempalace_evolve.cli serve --port 8765 --api-key your-secret-key\n# 请求时需带 header: X-API-Key: your-secret-key\n\n# 接口：POST \u002Fremember, \u002Frecall, \u002Fdigest, \u002Fevolve, \u002Fkg\u002Fadd, \u002Fkg\u002Fquery\n# GET \u002Fexport, \u002Fhealth\n```\n\n---\n\n## 记忆类型系统（认知科学三分法）\n\n借鉴认知科学的记忆分类，系统将记忆分为三种类型，各有不同的存储和检索策略：\n\n| 类型 | 含义 | 作用域 | 自动分类规则 |\n|------|------|--------|-------------|\n| **semantic**（语义记忆） | 事实、配置、决策 | 项目内 | decisions \u002F config \u002F architecture \u002F preferences room |\n| **episodic**（情景记忆） | 具体事件、对话记录 | 项目内 | progress \u002F general \u002F daily_summaries room |\n| **procedural**（程序记忆） | 经验、模式、教训 | **全局共享** | errors \u002F error_patterns room |\n\n**核心设计：procedural 记忆全局可见。**\n\n项目 A 踩过的坑（OOM、连接池泄漏、部署失败），项目 B 搜索时自动能找到。不需要手动配置跨项目关联。\n\n```python\n# 存储时自动分类\npalace.remember(\"数据库用 PostgreSQL\", room=\"decisions\")  # → semantic\npalace.remember(\"今天修了登录 bug\", room=\"progress\")       # → episodic\npalace.remember(\"OOM 时先查连接池 max 设置\", room=\"errors\") # → procedural（全局共享）\n\n# 也可以手动指定类型\npalace.remember(\"通用部署流程\", room=\"general\", memory_type=\"procedural\")\n```\n\n### 检索策略\n\n每次 `recall()` 自动执行两路并行搜索：\n\n```\n查询 \"内存溢出怎么办\"\n  ↓\n┌─────────────────────────────────────────────┐\n│ 搜索 1: 当前 wing（所有类型）               │\n│ 搜索 2: 全局 procedural（所有 wing 的经验） │\n└─────────────────────────────────────────────┘\n  ↓\n合并 + 去重 + KG 扩展\n  ↓\n返回结果（标记来源：direct \u002F procedural_global \u002F kg_expansion）\n```\n\n不需要任何参数控制，经验类记忆天然跨项目流动。\n\n---\n\n## 高级功能\n\n### 可配置评分规则\n\n不同类型的记忆重要性不同。默认情况下所有 room 使用相同的清理阈值，你可以通过 `scoring_config` 自定义：\n\n```python\npalace = MemPalace(\".\u002Fmemory\", scoring_config={\n    \"rooms\": {\n        \"decisions\": {\"weight\": 2.0, \"never_delete\": True},  # 决策永不自动删除\n        \"errors\": {\"weight\": 1.5, \"min_score\": 0.4},         # 错误模式提高保留阈值\n        \"config\": {\"weight\": 1.0, \"never_delete\": True},     # 配置永不删除\n    },\n    \"thresholds\": {\n        \"discard\": 0.3,      # 低于此分数 + 过期 → 清理（默认 0.3）\n        \"promote\": 0.7,      # 候选区高于此分数 → 晋升（默认 0.45）\n        \"stale_days\": 180,   # 决策超过此天数未访问 → 标记过时（默认 180）\n    }\n})\n```\n\n**规则说明：**\n- `never_delete: True`：该 room 的记忆在低分清理时被跳过，永远不会被自动删除\n- `weight`：影响评分计算权重（预留字段，当前版本用于优先级排序）\n- `thresholds` 全局生效，覆盖默认值\n\n### 混合检索（向量 + 知识图谱扩展）\n\n`recall()` 默认启用混合检索：先做向量语义搜索，再从结果中提取实体通过知识图谱扩展关联记忆。\n\n```python\n# 默认开启混合检索\nresults = palace.recall(\"Redis 缓存配置\")\n# 返回：\n# 1. 向量搜索直接命中的记忆\n# 2. 通过 KG 关联发现的相关记忆（标记 source: \"kg_expansion\"）\n\n# 关闭混合检索（纯向量搜索）\nresults = palace.recall(\"Redis 缓存配置\", hybrid=False)\n```\n\n**工作原理：**\n```\n查询 \"Redis 缓存配置\"\n  ↓\n向量搜索 → 找到 3 条直接相关记忆\n  ↓\n从结果中提取实体 → [\"Redis\", \"caching\"]\n  ↓\n查询知识图谱 → Redis --uses--> RedisCluster, Redis --stores_in--> AWS\n  ↓\n获取关联实体的记忆 → 补充到结果中\n  ↓\n返回：直接命中 + KG 扩展，去重后返回\n```\n\n### 增量进化\n\n`evolve()` 采用增量策略，不会每次全量扫描所有记忆：\n\n- **合并去重**：只扫描当天新增的记忆（不是全库对比）\n- **被动维护**：使用时间戳过滤，只处理上次进化后的变化\n- **记录进度**：每次进化完成后记录时间戳，下次从上次位置继续\n\n```python\n# 首次：处理所有记忆\npalace.evolve()\n\n# 后续：只处理新增的（快很多）\npalace.evolve()\n```\n\n对于大型记忆库（1000+ 条），增量模式将进化耗时从秒级降低到毫秒级。\n\n### 跨项目经验自动共享\n\n不需要手动配置。procedural 类型的记忆（错误模式、经验教训）自动在所有项目间共享：\n\n```python\n# 项目 A 存了一条错误经验\npalace_a = MemPalace(\".\u002Fmemory\", wing=\"project_a\")\npalace_a.remember(\"OOM 时先查连接池 max 设置\", room=\"errors\")\n# → 自动分类为 procedural，全局可见\n\n# 项目 B 搜索时自动找到\npalace_b = MemPalace(\".\u002Fmemory\", wing=\"project_b\")\nresults = palace_b.recall(\"内存溢出\")\n# → 返回 project_a 的经验，标记 source: \"procedural_global\"\n```\n\n**原理：**\n- `errors` \u002F `error_patterns` room 的记忆自动归类为 procedural\n- `recall()` 每次都会搜索全局 procedural 记忆（不只搜当前 wing）\n- 跨 wing 命中时自动记录 `cross_wing_hits`，用于智能晋升\n\n### Working Memory 缓存\n\n同一个话题连续提问时，不会重复搜索 ChromaDB：\n\n```python\n# 第一次搜索：走 ChromaDB\nresults = palace.recall(\"Redis 缓存配置\")\n\n# 紧接着问相似问题：直接返回缓存（不走数据库）\nresults = palace.recall(\"Redis 缓存怎么配的\")\n# → 话题相似度 > 0.8，命中 working memory，毫秒级返回\n```\n\n缓存在话题切换时自动失效，不需要手动管理。\n\n### 智能晋升机制\n\n当一条记忆被 3 个以上不同项目召回时，系统自动将其升级为 procedural 类型（全局共享）：\n\n```\n记忆 \"连接池 max 不要超过 CPU 核数 * 2\"\n  ↓\nproject_a 召回 → cross_wing_hits = 1\nproject_b 召回 → cross_wing_hits = 2\nproject_c 召回 → cross_wing_hits = 3 ← 触发晋升\n  ↓\n自动升级为 procedural → 之后所有项目都能搜到\n```\n\n不需要人工干预，系统根据实际使用模式自动识别\"通用经验\"。\n\n### 上下文长度控制\n\n防止注入过多记忆撑爆 LLM 上下文窗口：\n\n```python\n# 最多注入 2000 字符（约 500 token）\ncontext = palace.context_for(\"项目架构\", max_tokens=2000)\n\n# 小上下文模型（如 GPT-3.5）用更小的限制\ncontext = palace.context_for(\"项目架构\", max_tokens=800)\n```\n\n### 记忆导入\n\n从 JSON 文件或其他系统批量导入记忆：\n\n```python\n# 从 JSON 文件导入\nresult = palace.import_memories(\"exported_memories.json\")\n# {\"imported\": 42, \"skipped\": 3, \"errors\": []}\n\n# 从列表导入\npalace.import_memories([\n    {\"content\": \"API 用 FastAPI 框架\", \"room\": \"decisions\"},\n    {\"content\": \"数据库连接池 max=20\", \"room\": \"config\"},\n])\n```\n\nJSON 文件格式：每条记忆需要 `content` 字段，可选 `room` 和 `metadata`。\n\n### 记忆库统计\n\n```python\nstats = palace.stats()\n# {\n#     \"wing\": \"my_project\",\n#     \"total\": 156,\n#     \"rooms\": {\"decisions\": 23, \"errors\": 45, \"config\": 12, ...},\n#     \"kg_entities\": 34\n# }\n```\n\n---\n\n| 方法 | 说明 |\n|------|------|\n| `palace.remember(content, room, memory_type=)` | 存储记忆，自动分类类型（semantic\u002Fepisodic\u002Fprocedural） |\n| `palace.recall(query, limit=, hybrid=)` | 语义搜索：当前 wing + 全局 procedural 并行检索 |\n| `palace.forget(drawer_id)` | 删除指定记忆 |\n| `palace.digest(conversation)` | 从对话自动提取知识 + KG 三元组 |\n| `palace.context_for(query, max_tokens=)` | 获取上下文，自动控制长度 |\n| `palace.import_memories(source)` | 从 JSON 文件或列表批量导入 |\n| `palace.export(format, output)` | 导出记忆为 JSON 或 Markdown |\n| `palace.stats()` | 查看记忆库统计（数量、分布、KG 实体数） |\n| `palace.add_fact(s, p, o)` | 添加知识图谱三元组 |\n| `palace.query_entity(entity)` | 查询实体关系 |\n| `palace.evolve(transcript)` | 执行一次增量进化周期 |\n\n---\n\n## CLI 命令\n\n```bash\npython -m mempalace_evolve.cli setup --wing my_project   # 一键配置 MCP\npython -m mempalace_evolve.cli demo          # 一键演示全部功能\npython -m mempalace_evolve.cli doctor        # 检查安装环境\npython -m mempalace_evolve.cli playground    # 交互式 REPL\npython -m mempalace_evolve.cli remember \"内容\" --room decisions\npython -m mempalace_evolve.cli recall \"搜索词\"\npython -m mempalace_evolve.cli evolve\npython -m mempalace_evolve.cli export --format json -o memories.json\npython -m mempalace_evolve.cli export --format markdown\npython -m mempalace_evolve.cli serve --port 8765\npython -m mempalace_evolve.cli serve --port 8765 --api-key mysecret\n```\n\n---\n\n## 项目结构\n\n```\nsrc\u002Fmempalace_evolve\u002F\n├── sdk.py               # 主 SDK（MemPalace 类）\n├── exceptions.py        # 自定义异常（StorageError\u002FValidationError 等）\n├── export.py            # 记忆导出（JSON\u002FMarkdown）\n├── cli.py               # 命令行工具\n├── setup_wizard.py      # 一键安装向导（mempalace setup）\n├── demo.py              # 一键演示\n├── doctor.py            # 环境检查\n├── playground.py        # 交互式 REPL\n├── terminal.py          # 终端彩色输出\n├── core\u002F                # 核心引擎\n│   ├── chroma_helper.py    # ChromaDB 向量存储\n│   ├── knowledge_graph.py  # SQLite 知识图谱\n│   ├── lifecycle.py        # 生命周期（TTL\u002F遗忘曲线\u002F清理）\n│   ├── consolidation.py    # 记忆合并去重\n│   ├── adaptive_scorer.py  # 自适应评分\n│   ├── layers.py           # 4 层记忆架构\n│   └── config.py           # 配置管理\n├── evolution\u002F           # 自进化管道\n│   ├── pipeline.py      # 进化主流程\n│   ├── candidate.py     # 候选提取器\n│   ├── reviewer.py      # 评审打分\n│   └── opportunistic.py # 4 项被动维护\n└── adapters\u002F            # Agent 适配器\n    ├── mcp_server.py       # MCP 协议（Claude\u002FCursor）\n    ├── openai_adapter.py   # OpenAI Function Calling\n    ├── langchain_adapter.py # LangChain Tools\n    └── rest_api.py         # HTTP REST API（支持 API key 认证）\n```\n\n## License\n\nMIT","mempalace-evolve 是一个为 AI 代理设计的自进化记忆系统，提供持久化的记忆存储，并支持自动学习、知识图谱和多代理协作。该项目的核心功能包括自动筛选、打分和淘汰记忆内容，以及通过向量语义搜索和知识图谱实现高效检索。它不依赖于特定框架，可以与 OpenAI、Claude、LangChain 等多种平台无缝集成。适合需要增强跨会话记忆能力或优化长期知识管理的 AI 应用场景，特别对于希望提升对话连续性和智能性的开发者来说是一个强有力的选择。",2,"2026-06-11 04:03:06","CREATED_QUERY"]