Metadata-Version: 2.5
Name: memoria-framework
Version: 0.3.6
Summary: 通用 AI Agent 记忆框架 — 零成本起步，全功能扩展
Project-URL: Homepage, https://github.com/fleg45/memory_framework
Project-URL: Repository, https://github.com/fleg45/memory_framework
Author: yh
License-Expression: MIT
Keywords: agent,ai,llm,memory,rag
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: aiomysql>=0.2
Requires-Dist: jieba3k>=0.35
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: memoria[dev,llm,local-embed,postgres,redis,server,vector]; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Provides-Extra: llm
Requires-Dist: openai>=1.0; extra == 'llm'
Provides-Extra: local-embed
Requires-Dist: sentence-transformers>=2.7; extra == 'local-embed'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == 'postgres'
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == 'redis'
Provides-Extra: server
Requires-Dist: fastapi>=0.110; extra == 'server'
Requires-Dist: uvicorn>=0.27; extra == 'server'
Provides-Extra: vector
Requires-Dist: numpy>=1.26; extra == 'vector'
Requires-Dist: qdrant-client>=1.7; extra == 'vector'
Description-Content-Type: text/markdown

# Memoria

通用 AI Agent 记忆框架 —— 零成本起步，全功能扩展。

Memoria 为 AI Agent 提供多层级、多类型的长期记忆：从短时工作记忆到长期归档，覆盖 8 种记忆类型，并通过五管线上下文召回把「参考信息、用户画像、技能、情绪、约束」一次性交还给模型，让 Agent 跨会话保持连贯。

## 安装

```bash
pip install memoria
```

可选扩展：

| Extra | 说明 |
|---|---|
| `memoria[llm]` | LLM 驱动的类型自动分类（OpenAI 兼容接口） |
| `memoria[vector]` | 向量检索（Qdrant） |
| `memoria[local-embed]` | 本地向量嵌入（sentence-transformers） |
| `memoria[redis]` | Redis 存储后端 |
| `memoria[postgres]` | PostgreSQL 存储后端 |
| `memoria[all]` | 全部扩展 |

## 快速开始

```python
import asyncio
from memoria import MemoriaManager
from memoria.config import DictStoreConfig, MemoriaConfig

# 内存版配置（零依赖起步）；持久化时把 DictStoreConfig 换成 MySQLStoreConfig 等
config = MemoriaConfig(
    stores={
        "working": DictStoreConfig(max_items=200, ttl_seconds=1800),
        "short_term": DictStoreConfig(max_items=5000, ttl_seconds=0),
        "long_term": DictStoreConfig(max_items=5000, ttl_seconds=0),
    },
    indexes={
        "working": [],
        "short_term": ["keyword", "temporal"],
        "long_term": ["keyword", "temporal"],
    },
    default_layer="short_term",
)

async def main():
    manager = MemoriaManager(config)
    await manager.initialize()

    memory_id = await manager.store(
        "用户最喜欢的验证饮料是冷萃铁观音-0827",
        types=["semantic"],
        importance=0.6,
    )

    ctx = await manager.contextual_recall("用户最喜欢的验证饮料是什么")
    print(ctx.to_prompt())          # 结构化的多管线召回上下文
    print(await manager.stats())    # 各层记忆数量与生命周期分布

    await manager.close()

asyncio.run(main())
```

## 核心概念

**五层记忆**（`sensory` → `working` → `short_term` → `long_term` → `archive`）

- `sensory`：感知缓冲，短期原始输入
- `working`：工作记忆，当前任务上下文
- `short_term`：短期记忆，跨会话近期事实
- `long_term`：长期记忆，稳定知识与经验
- `archive`：归档，冷数据（通过 `query_archive` 检索）

**八种记忆类型**：`episodic`（事件）、`semantic`（事实）、`procedural`（流程/技能）、`relational`（关系）、`affective`（情绪）、`spatial`（空间）、`social`（用户画像）、`meta`（规则/约束）。

**五管线上下文召回**：`contextual_recall()` 聚合 reference / profile / skills / emotion / constraints 五条管线，返回 `MemoryContext`。

## 主要 API

| 方法 | 说明 |
|---|---|
| `store(content, *, types, importance, ...)` | 存入一条记忆，返回 `memory_id` |
| `recall(query, *, layers, types, ...)` | 返回 `list[MemoryRecord]` |
| `contextual_recall(query, *, limit, ...)` | 五管线召回，返回 `MemoryContext` |
| `forget(memory_id)` / `remember(memory_id)` | 遗忘 / 恢复一条记忆 |
| `link(source_id, predicate, target_id)` | 建立记忆间关系 |
| `stats()` | 各层记忆计数与生命周期分布 |

## DeepSeek Harness 集成

Memoria 提供 `memoria.plugin_server`（stdio JSON-RPC 服务），配合 [`dsh-memoria`](https://www.npmjs.com/package/dsh-memoria) npm 插件，可作为 DeepSeek Harness 的原生长时记忆插件：每个会话自动注入召回上下文，无需显式调用召回工具。

```bash
pip install memoria
dsh plugin --profile web add dsh-memoria
```

## License

MIT
