Metadata-Version: 2.4
Name: echon
Version: 0.0.1
Summary: Agent 记忆模块 — 记忆演化：自动去重、合并、衰减
Project-URL: Repository, https://github.com/KenyonY/echon
Author: Kenyon Yang
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: aiohttp
Requires-Dist: chonkie>=1.6.1
Requires-Dist: flaxkv2
Requires-Dist: lancedb
Requires-Dist: maque
Requires-Dist: markitdown[docx,pdf]>=0.1.5
Provides-Extra: all
Requires-Dist: chonkie; extra == 'all'
Requires-Dist: flexllm; extra == 'all'
Requires-Dist: markitdown[docx,pdf]; extra == 'all'
Provides-Extra: doc
Requires-Dist: chonkie; extra == 'doc'
Requires-Dist: markitdown[docx,pdf]; extra == 'doc'
Provides-Extra: doc-heavy
Requires-Dist: mineru[pipeline]; extra == 'doc-heavy'
Provides-Extra: llm
Requires-Dist: flexllm; extra == 'llm'
Description-Content-Type: text/markdown

# echon

Agent 记忆模块 — 自动去重、合并、衰减的长期记忆。

## 特性

- **向量检索** — 基于 LanceDB 的语义相似度检索
- **自动去重** — 语义相同的记忆不会重复存储
- **智能合并** — 相似但不完全相同的记忆自动合并（可选 LLM 辅助）
- **时间衰减** — 指数衰减 + 访问频率加成，自动清理过期记忆
- **文档摄入** — 支持 PDF/Word/PPT/HTML 等格式解析并切分为记忆片段
- **记忆提取** — 从对话文本中自动提取 fact/event/preference 类型记忆

## 安装

```bash
pip install echon
```

可选依赖：

```bash
pip install echon[doc]       # 文档解析（markitdown + chonkie）
pip install echon[doc-heavy] # 高精度文档解析（MinerU）
pip install echon[llm]       # LLM 辅助合并/提取（flexllm）
pip install echon[all]       # doc + llm
```

## 快速开始

```python
from echon import Memory

with Memory("my-agent", embedding_url="http://localhost:8001/v1") as mem:
    # 添加记忆
    mem.add("用户是一名后端工程师", memory_type="fact", importance=0.9)
    mem.add("用户喜欢简洁的代码风格", memory_type="preference", importance=0.8)

    # 检索
    results = mem.recall("代码怎么写比较好", top_k=3)
    for r in results:
        print(f"[{r['memory_type']}] {r['content']}  (score={r['score']})")

    # 重复内容自动去重
    mem.add("用户是一名后端工程师")  # 不会重复存储
```

## 文档摄入

```python
from echon import Memory, DocumentParser

parser = DocumentParser(backend="markitdown", chunk_size=512)
with Memory("my-agent", parser=parser, embedding_url="http://localhost:8001/v1") as mem:
    ids = mem.ingest("report.pdf", importance=0.7)
    print(f"摄入 {len(ids)} 条记忆")
```

## 记忆提取

```python
# 从对话文本中自动提取记忆
ids = mem.extract("我是数据工程师，最近在研究 RAG 架构，喜欢用 Python")
```

## 配置

```python
from echon import EchonConfig, Memory

config = EchonConfig(
    duplicate_threshold=0.95,   # 去重阈值
    merge_threshold=0.92,       # 合并阈值
    decay_lambda=0.001,         # 衰减系数（每小时）
    forget_threshold=0.05,      # 遗忘阈值
    cleanup_interval=10,        # 每 N 次 recall 触发衰减检查
)
mem = Memory("my-agent", config=config, embedding_url="http://localhost:8001/v1")
```

## License

Apache-2.0
