\r \r

Agent Long-Term Memory · AI 智能体长期记忆\r

\r

Install from GitHub · 从 GitHub 安装\r

\r

git clone https://github.com/exp007/agent-long-term-memory.git ~/.codex/skills/agent-memory\r
```\r
\r
Three-tier persistent memory shared at `~/.codex/agent_memory/` across all projects.\r
\r
三层持久记忆，数据存在 `~/.codex/agent_memory/`，所有项目共享。\r
\r
## Quick Start · 快速开始\r
\r
```python\r
from agent_memory import get_memory\r
\r
mem = get_memory()\r
mem.remember("name", "Alice")\r
mem.recall("name")                    # -> "Alice"\r
mem.recall("favorite color")          # -> None (not yet stored)\r
```\r
\r
## API Reference · API 参考\r
\r
### Tier 2: Entity Memory · 实体记忆（结构化事实，SQLite）\r
\r
| Method | Signature | Description |\r
|--------|-----------|-------------|\r
| `remember` | `(key, value, evidence="", confidence=1.0)` | Store a structured fact · 存储结构化事实 |\r
| `remember` | `(content, tags=None, ...)` | Store a fact in v1 compat mode |\r
| `recall` | `(key_or_query, limit=10, tags=None)` | Lookup by key or search by content · 按 key 精确查或按内容搜 |\r
| `recall_card` | `(key)` | Get the full EntityCard · 获取完整卡片 |\r
| `get_profile` | `()` | Return all entity cards · 获取全部画像 |\r
| `search_entities` | `(keyword)` | Fuzzy search across keys and values · 模糊搜索 |\r
| `forget_entity` | `(key)` | Delete an entity card · 删除 |\r
| `clean_stale` | `(threshold=0.3)` | Remove low-confidence cards · 清理低置信度 |\r
| `entity_count` | property | Number of entity cards · 卡片数量 |\r
\r
### Tier 3: Episodic Memory · 情景记忆（对话片段，ChromaDB）\r
\r
| Method | Signature | Description |\r
|--------|-----------|-------------|\r
| `archive` | `(content, summary="")` | Store a conversation chunk · 存储对话片段 |\r
| `recollect` | `(query, n_results=5)` | Semantic search · 语义检索 |\r
| `episodic_count` | property | Number of stored episodes · 片段数量 |\r
\r
### Tier 1: Short-Term Memory · 短期记忆（滑动窗口）\r
\r
| Method | Signature | Description |\r
|--------|-----------|-------------|\r
| `add_turn` | `(user_text, assistant_text)` | Record a turn · 记录一轮对话 |\r
| `get_recent` | `(n=None)` | Get recent messages · 获取最近消息 |\r
| `clear_short_term` | `()` | Clear buffer · 清空缓冲区 |\r
\r
### RAG Context Building · RAG 上下文构建\r
\r
| Method | Signature | Description |\r
|--------|-----------|-------------|\r
| `build_context` | `(user_query="", episodic_top_k=3)` | Full MemoryContext · 完整上下文 |\r
| `build_system_extension` | `(user_query="", episodic_top_k=3)` | Prompt injection string · 系统提示扩展 |\r
\r
### Auto Extraction · 自动抽取\r
\r
| Method | Signature | Description |\r
|--------|-----------|-------------|\r
| `auto_remember` | `(conversation_text)` | Extract entities from text · 从对话中抽取实体。有 OpenAI key 用 LLM，无则用正则兜底。 |\r
\r
### v1 Compat API · v1 兼容接口\r
\r
`add_fact`, `get_fact`, `get_facts`, `list_facts`, `forget`, `supersede`, `forget_stale`, `learn`, `get_lessons`, `apply_lesson`, `track_entity`, `get_entity`, `update_entity`, `list_entities`, `link_fact_to_entity`, `stats`, `export_json`, `close`\r
\r
## Standard Integration Pattern · 标准集成流程\r
\r
```\r
session start:       mem = get_memory(); inject mem.get_profile() into system prompt\r
every user message:  mem.add_turn(user_msg, assistant_msg)\r
significant facts:   mem.remember(key, value, evidence)\r
                     mem.auto_remember(conversation_text)  # auto-extract · 自动抽取\r
conversation end:    mem.archive(full_conversation, summary)\r
periodic cleanup:    mem.clean_stale(0.3); mem.forget_stale(30)\r
shutdown:            mem.close()\r
```\r
\r
## Dependencies · 依赖\r
\r
```\r
pip install chromadb>=0.4.0 openai>=1.0.0\r
```\r
\r
OpenAI key is optional — if unset, entity extraction falls back to regex patterns.\r
OpenAI key 可选——不配也能用正则兜底。\r