mem8

Installation from PyPI

pip install mem8-fs

The distribution name is mem8-fs; the Python import package remains mem8:

from mem8.api import Memory

mem8 是一个面向 AI Agent 的本地优先长期记忆 Python 包。Markdown 是记忆正文的事实来源；SQLite 保存元数据、链接和评估记录，并通过 FTS5 BM25、sqlite-vec 向量检索及 RRF 融合提供混合检索。LLM 负责从对话中提炼、判断和更新记忆，也用于检查并修复断链。

当前版本为 0.1.0，支持本地 Markdown 记忆、核心记忆注入、按 ID 或路径查询、BM25 与向量混合检索、对话驱动的记忆更新、断链检查修复，以及 retrieval、update、check 评估。默认记忆根目录是当前工作目录下的 .mem8。

环境要求

• Python 3.11 或更高版本。
• 使用 uv 管理依赖、虚拟环境和命令。
• 默认 LLM 为 Anthropic，需要配置 ANTHROPIC_API_KEY。
• 至少安装一种 Embedding Provider：Local、OpenAI 或 Voyage。
• Local Embedding 首次加载模型时可能需要联网下载模型文件。

当前内置 LLM 实现仅支持 Anthropic。openai extra 目前只提供 OpenAI Embedding，不提供 OpenAI LLM。

安装与初始化

安装项目

安装开发、评估和默认 Local Embedding 依赖：

uv sync --extra dev --extra evals --extra local

也可以按需选择 Embedding Provider：

uv sync --extra local   # 本地 sentence-transformers，默认配置
uv sync --extra openai  # OpenAI Embedding
uv sync --extra voyage  # Voyage Embedding

初始化记忆目录

uv run mem8 init

初始化后，mem8 使用以下目录结构：

.mem8/
├── core/       # 用户注入的只读核心记忆，首次注入时创建
├── notes/      # Agent 创建和维护的普通记忆，首次写入时创建
├── mem8.db     # SQLite 数据库及索引
└── mem8.toml   # Provider 与存储配置

所有卡片路径都相对于记忆根目录，例如 notes/context.md。所有 CLI 命令均可通过 --memory-root PATH 指定其他完整记忆根目录；Python API 则通过 Memory.open(memory_root=...) 指定。mem8 不会在自定义根目录中再创建第二层 .mem8。

打开旧工作区时，如果存在 <memory_root>/.mem8/mem8.toml 或 <memory_root>/.mem8/mem8.db，且根目录不存在同名文件，mem8 会自动将其迁移到根目录。新旧位置同时存在同名文件时会停止迁移，要求人工处理冲突。

journal/ 属于后续恢复机制设计，当前版本不会创建或使用该目录。

CLI 使用

初始化、迁移与配置

# 初始化工作区；重复执行是安全的
uv run mem8 init

# 单独执行幂等数据库迁移
uv run mem8 migrate

# 修改配置
uv run mem8 config set llm.model claude-sonnet-4-6
uv run mem8 config set llm.max_tokens 4096
uv run mem8 config set embedding.provider local
uv run mem8 config set embedding.model all-MiniLM-L6-v2
uv run mem8 config set embedding.dim 384
uv run mem8 config set storage.db_filename mem8.db

配置保存在 <memory-root>/mem8.toml，也可以使用环境变量覆盖：

• MEM8_LLM__MODEL
• MEM8_LLM__MAX_TOKENS
• MEM8_EMBEDDING__PROVIDER
• MEM8_EMBEDDING__MODEL
• MEM8_EMBEDDING__DIM
• MEM8_STORAGE__DB_FILENAME

核心记忆、检索与查询

# 注入核心记忆，仅接受 Markdown 文件
uv run mem8 core inject ./seed.md

# BM25 + Vector + RRF 混合检索
uv run mem8 retrieve "context overflow" --topk 5 --similarity 0.55

# 按 ID 或相对路径查询，二者必须且只能提供一个
uv run mem8 query --card-id 1
uv run mem8 query --path notes/context.md

更新与检查

更新命令接收 JSONL 历史对话：

uv run mem8 update --messages messages.jsonl
uv run mem8 check

messages.jsonl 的每个非空行必须包含 role 和 content：

{"role":"user","content":"I prefer concise answers."}
{"role":"assistant","content":"Understood."}

update 执行“压缩 → 决策 → 写回”流程；check 扫描并尝试修复断链。

评估

uv run mem8 eval --suite retrieval
uv run mem8 eval --suite update --record
uv run mem8 eval --suite check --baseline
uv run mem8 eval --suite all --record

--record 只持久化普通评估运行，不会自动将其设为基线。--baseline 仅在数据库已有 is_baseline=True 的显式基线时计算相对差值；门禁指标下降超过 5% 时命令返回非零状态。当前 CLI 尚未提供设置基线的命令，可以通过 Python API 写入基线。

Python API

打开与使用记忆

from mem8 import Memory
from mem8.domain.message import Message

with Memory.open() as memory:
    results = memory.retrieve(
        "how should context overflow be handled?",
        topk=5,
        similarity=0.55,
    )

    if results:
        card = memory.query(card_id=results[0].card_id)

    update_report = memory.update([
        Message(role="user", content="I prefer concise answers."),
        Message(role="assistant", content="Understood."),
    ])

    check_report = memory.check()
    core_card_id = memory.inject_core_card("seed.md")

Memory.open 支持注入自定义组件，便于测试或替换 Provider：

memory = Memory.open(
    memory_root="/path/to/memory",
    llm=my_llm,
    embedding=my_embedding,
    tokenizer=my_tokenizer,
    settings=my_settings,
)

公开方法

Memory.retrieve(prompt, topk, similarity) -> list[RetrievalResult]
Memory.query(card_id=..., path=...) -> RetrievalResult
Memory.update(messages) -> UpdateReport
Memory.check() -> CheckReport
Memory.inject_core_card(source_md_path) -> int
Memory.record_eval_run(run) -> int
Memory.list_eval_runs(eval_name) -> list[EvalRun]
Memory.get_baseline_eval_run(eval_name) -> EvalRun | None

retrieve 要求 prompt 非空、topk > 0，且 similarity 位于 [0, 1]。query 必须且只能提供 card_id 或 path 之一。

如需创建评估基线，可构造 is_baseline=True 的 EvalRun：

from mem8.domain.eval_run import EvalRun

memory.record_eval_run(EvalRun(..., is_baseline=True))

写入约束

• Agent 新卡只能写入 notes/。
• 核心记忆只能通过 inject_core_card 或 core inject 注入，更新流程不得修改核心卡。
• 路径必须是安全的根目录相对 Markdown 路径；绝对路径、反斜杠和目录穿越会被拒绝。
• 创建卡片时禁止覆盖已有路径。
• 每张卡片最多 4096 token、最多 8 个 Markdown 出链；链接按 1 token 计数。
• 修改链接前会重新检查来源卡和目标卡的 token 与出链限制。
• 混合检索中任一路结果足够强即可进入 RRF 候选，避免单路弱分误杀结果。

开发指南

质量检查

uv run pytest
uv run ruff check mem8 evals tests
uv run mypy mem8 evals

测试覆盖单元、集成和端到端场景。提交代码前应确保 pytest、Ruff 和 mypy 全部通过。

项目文档

• 产品需求
• 开发设计

prd.md 是产品要求基线；dev.md 包含当前实现梳理与后续演进设计。README 以当前仓库中实际可运行的公开能力为准。

当前边界

dev.md 中的 audit/repair 分离、sync、reindex、recover、journal 恢复和 OpenAI LLM 等属于后续设计目标，当前公开 API 与 CLI 尚未提供这些入口。