# Cortex OS · 仿生认知引擎

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

零依赖记忆引擎，为 AI Agent 提供**皮层记忆**、**会话状态管理**、**三段式上下文组装**、**技能自进化**。

A zero-dependency memory engine providing AI Agents with cortical memory, session state management, three-segment context assembly, and self-evolving skills.

---

## 安装

```bash
pip install -e .               # 从源码安装（核心引擎，零外部依赖）
pip install -e ".[mcp]"        # 含 MCP Server（mcp>=2.0.0）
pip install -e ".[all]"        # 全部可选依赖（向量 + YAML）
```

> 未发布到 PyPI，使用源码安装（`pip install -e .`）。

## 快速开始

```python
from core import MemoryService

ms = MemoryService("store.db")

# 记忆
ms.record("我用 RTX 5060，8GB 显存")
results = ms.recall("RTX")
ms.consolidate()

# 多步骤任务
ms.init_session("sess_1", initial_step="identity_check")
ms.update_state("sess_1", fields={"name": "张三"})
ms.update_state("sess_1", step="doc_upload")
ctx = ms.assemble_context("sess_1", "上传照片")

# 可视化
ms.export_graph_html("./graph.html")

# 技能引擎
ms.skill_add("deploy-docker", "Docker deployment workflow", trigger_tags=["Docker"])
ms.skill_import([{"name": "lint", "description": "Code linting"}], source_agent="claude")
```

## 架构

```
第 1 层: 皮层存储   — SQLite FTS5 + 关系表 + 向量（可选）        [schema.py, vector.py]
第 2 层: 海马索引   — 工作记忆（7天TTL）+ 待巩固队列            [record.py]
第 3 层: 巩固引擎   — B级冲突检测 + LLM 批处理（可选）+ 时间裁决   [consolidate.py]
第 4 层: 会话状态   — current_step / collected_fields / pending_actions + 回滚  [session.py]
第 5 层: 上下文组装 — [STATE] + [MEMORY] + [RECENT] + [INSTRUCTION] 三段式      [context.py]
第 6 层: 适配层     — MCP Server（stdio / streamable-http）      [adapters/mcp_server.py]
第 7 层: 可视化     — 知识图谱 JSON / D3.js HTML 页面 / Obsidian MD 导出  [memory_viz.py]
第 8 层: 技能引擎   — 记忆提炼技能 / 冲突合成 / 外部导入融合 / 衰减淘汰  [skill.py, skill_import.py]
辅助:   config.py（配置词表）/ encoding.py（感知编码）/ llm.py（LLM工具+token追踪）/ summarizer.py / import_history.py
```

## Agent 接入（统一 MCP）

```bash
python -m adapters.mcp_server                          # stdio
python -m adapters.mcp_server --transport http         # HTTP
# Docker: docker-compose.yml 中 cortex-os 服务已注释，按需启用
```

| Agent | 配置 |
|-------|------|
| Claude Code | `adapters/mcp.json`（示例，MCP 2.0 streamable-http） |
| 任意 MCP 客户端 | `python -m adapters.mcp_server --transport http` |

## API 概览

| 方法 | 说明 |
|------|------|
| `record(text)` | 记录对话 |
| `recall(query)` | 搜索记忆 |
| `consolidate()` | 触发巩固 |
| `init_session(id)` | 初始化会话 |
| `update_state(id, fields, step)` | 更新任务状态 |
| `rollback_state(id)` | 回滚到安全快照 |
| `assemble_context(id, query)` | 组装三段式上下文 |
| `import_history(id, messages)` | 批量导入历史对话 |
| `memory_visualize()` | 导出知识图谱 JSON |
| `export_graph_html(path)` | 生成 D3.js 交互图谱 |
| `export_markdown(dir)` | 导出 Obsidian Markdown Vault |
| `skill_add(name, desc)` | 新增技能 |
| `skill_list()` | 列出技能 |
| `skill_merge(ids)` | 合并多项技能 |
| `skill_import(skills)` | 导入外部 Skill |
| `skill_import_claude(dir)` | 导入 Claude Code Skill |
| `skill_import_codex(path)` | 导入 Codex CLI 配置 |
| `skill_import_hermes(dir)` | 导入 Hermes Skill |
| `skill_import_fusion(skills)` | 导入 + 自动融合 |
| `get_token_usage()` | 查询 LLM token 消耗 |
| `health_check()` | LLM/向量连通性自检 |

MCP 工具: `memory_record` / `memory_recall` / `memory_consolidate` / `context_assemble` / `state_update` / `state_rollback` / `memory_import` / `memory_visualize` / `export_graph_html` / `export_markdown` / `skill_add` / `skill_list` / `skill_merge` / `skill_import` / `skill_import_claude` / `skill_import_codex` / `skill_import_hermes` / `skill_import_fusion`

## 配置

```yaml
# config.yaml
trigger_threshold: 50
trigger_interval: 86400
max_recent_turns: 3
skill_threshold: 5
llm_batch_size: 50
llm_endpoint: https://your-api/v1/chat/completions  # 可选
llm_model: deepseek-chat
llm_api_key: sk-xxx
embedding_endpoint: http://localhost:8080/v1/embeddings  # 可选
embedding_model: bge-large-zh-v1.5
```

不配 LLM/向量也能用——巩固引擎退化为纯规则模式，搜索依赖 FTS5 + 关系。

## 运行测试

```bash
python -m unittest discover tests -v   # 170 项测试
```