Metadata-Version: 2.4
Name: codon-memory
Version: 0.2.0
Summary: DNA 启发的硅基 Codon 记忆系统：时序回忆通道 + 记忆生命周期治理的记忆中间件
Author: Codon Memory Authors
License: MIT
Keywords: memory,llm,agent,retrieval,temporal-recall,sqlite
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: scikit-learn>=1.2
Provides-Extra: faiss
Requires-Dist: faiss-cpu>=1.7; extra == "faiss"
Provides-Extra: embed
Requires-Dist: sentence-transformers>=2.2; extra == "embed"
Provides-Extra: all
Requires-Dist: faiss-cpu>=1.7; extra == "all"
Requires-Dist: sentence-transformers>=2.2; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# Codon 记忆系统

DNA 启发的硅基记忆中间件：**时序回忆通道 + 记忆生命周期治理 + 事实层 + 无监督层级**。
核心主张——用恒定大小的上下文处理无限增长的对话，解决 RAG/长上下文在时间维度上的结构性盲区。

## 30 秒上手

```bash
pip install -e .                    # 核心依赖（torch / numpy / scikit-learn）
pip install -e ".[faiss,embed]"     # 推荐：FAISS 索引 + MiniLM 嵌入
codon-memory doctor                 # 环境健康检查
```

```python
from codon_memory.agent import MemoryAgent
from codon_memory.local_store import LocalMemoryStore
from codon_memory.facts import SemanticFactStore
from codon_memory.data_real import OllamaEmbedder
from codon_memory.api_client import ApiChatClient

store = LocalMemoryStore("data/memory.db",
                         embedder=OllamaEmbedder(model_name="bge-m3"))
facts = SemanticFactStore("data/memory.db", embedder=store.embedder)
agent = MemoryAgent(store, ApiChatClient(model="deepseek-v4-flash").chat,
                    fact_store=facts)

agent.handle("我的名字是小王")            # 写入记忆 + 抽取事实
answer = agent.handle("我的名字是什么？")    # 重开会话后依然答对
plan = agent.generate("结合我的情况规划周末方案")  # 个性化生成
```

## 命令行

```bash
python -m codon_memory demo      # 合成时序回忆 Demo
python -m codon_memory agent     # 多会话记忆 Agent 演示（需 LLM_API_KEY 或 Ollama）
python -m codon_memory memory    # 本地记忆库遗忘/固化演示
python -m codon_memory doctor    # 环境健康检查
```

安装后也可直接运行 `codon-memory <命令>`。

## 核心能力（均为实测）

| 能力 | 结果 |
|---|---|
| 时序回忆（"倒数第 N 条"） | 合成 100%；agent 循环 93.3% vs RAG 6.7% |
| Agent 循环 | 98.0% vs RAG 58.8%（p<0.0001） |
| 真实多会话（教事实→重开→仲裁→生成） | 100% / 100% / 100% |
| 长对话成本 | 480 轮生命周期节省 77%（token 实测） |
| 零标签记忆治理 | 无监督层级驱动，家族覆盖 100% vs 40% |
| 幻觉控制 | 溯源门控：幻觉率 → 0% |
| 检索规模化 | FAISS：百万级 23ms（暴力 192ms，8×） |
| 测试 | 91 个全绿 |

## 配置

- 在线生成：`LLM_API_KEY` / `LLM_BASE_URL` / `LLM_CHAT_MODEL`
  （OpenAI 兼容，DeepSeek 等；结构化抽取需 `thinking:disabled`，客户端已内置）
- 本地生成/嵌入：Ollama（bge-m3 等）
- 记忆库：默认 `data/memory.db`，`MemoryLimits` 可热调整容量/保底/上限/固化阈值
- 检索：`ann=True` 默认开启 FAISS 索引（规模超 2 万条自动切换）

## 文档

- [部署文档.md](./部署文档.md)：成本收益表、部署决策表、上线检查清单
- [总结.md](./总结.md)：46 轮迭代历程与全部实验数据
- [项目评估报告.md](./项目评估报告.md)：总体评估（综合 9.0/10）
- [Codon 双链类脑记忆架构.md](./Codon 双链类脑记忆架构.md)：架构设计

## 发布与 CI

- 构建：`pip install build && python -m build`（产出 sdist + wheel，`twine check` 通过）
- CI：GitHub Actions（`.github/workflows/ci.yml`）在 push/PR 时跑
  ubuntu/windows × Python 3.10/3.12 全量测试与 CLI 冒烟
- 发布：打 `v*` tag 触发 `.github/workflows/publish.yml` 自动构建并上传 PyPI
  （需仓库配置 `PYPI_TOKEN` secret）
