zzjzzb/ai-memory

ai-memory

给 Agent 用的本地记忆层：按项目存短中长期记忆，超长会话只往模型塞预算内的一小包；可挂 DeepSeek Harness。

License: MIT OR Apache-2.0
Rust

面向 agent harness 的本地 Rust + SQLite 记忆：按项目存工作 / 情景 / 画像笔记，并为下一次模型调用提供按 token 预算打包的内容（而非完整对话记录）。可选 DeepSeek Harness 插件。

它不会把 100 万 token 的对话记录塞进 prompt，不会在后台跑 consolidate，也不会和 LLM 通信。

安装到 DeepSeek Harness

复制粘贴指南（固定 commit、allowBuilds、你应该看到什么）：

- 英文：docs/INSTALL_DSH.md
- 中文：docs/INSTALL_DSH.zh-CN.md

dsh plugin --profile web add github:zzjzzb/ai-memory#

用 git ls-remote https://github.com/zzjzzb/ai-memory.git refs/heads/main 获取 （左列）。添加后：dsh --profile web --dump-config 必须显示 # == dsh-ai-memory。

根目录的 package.json 是 dsh bundle（npm 名 dsh-ai-memory）。Cargo.toml 是 Rust crate（包名 ai-memory）。同一个仓库，两个 manifest，不是两个产品。

文档： USAGE（英文） · 用法（中文） · ARCHITECTURE（英文） · 架构（中文） · DeepSeek Harness（英文） · DeepSeek Harness（中文）

旗舰 dsh 演示： SME 支持 / 运维场景 ·  —— 一个长会话，按预算打包，不是 JS 记忆重写。

贡献： CONTRIBUTING.md · 参与贡献 · Issues · Pull requests

场景 → 调用 → 得到

一个长会话，许多相关工单，聊天记录比模型上下文还大（约 100 万或更小）：存下每一轮，然后 prefetch_within_budget。置顶项和高分命中填满 2k–32k token 的包（默认 ceil(chars/4)）。

use ai_memory::{open, MemoryPolicy, MemoryStore, RememberRequest, Tier, TokenBudget};

fn main() -> ai_memory::Result {
let store = open("./memory.db")?;
store.create_project("support-bot", MemoryPolicy::chat())?;
let session = store.session("support-bot")?;

session.remember_turn([
RememberRequest::new("User prefers dark mode").with_tier(Tier::Profile),
RememberRequest::new("Ticket: sidebar overlap").with_tier(Tier::Working),
])?;

let pack = session.prefetch_within_budget("sidebar", TokenBudget::new(8_192))?;
let _system = pack.render(); // your harness system prompt — not the full history

session.compact_working()?;       // optional, explicit, offline extractive fold
session.end_turn_consolidate()?;  // 可选，显式 TTL + 提升
Ok(())
}

cargo test
cargo run --example harness_loop_sim
cargo run --bin ai-memory -- --in-memory memory_remember '{"text":"hi","tier":"profile"}'

open() 会应用 WAL 及其他 SQLite 默认设置。当你拥有真实的 Embedder 时，注入它；默认的 HashEmbedder 是离线的。可选的 --features sqlite-vec。

该做 / 不该做

| 该做 | 不该做 |
|----|--------|
| 用 remember_turn 持久化轮次 | 把完整对话记录塞进模型 |
| prefetch_within_budget(query, TokenBudget { max_tokens }) | 指望 1M token 能塞进一个 prompt |
| pin 必须保留的事实 | 自动整合或自动压缩 |
| 在你确实需要时调用 compact_working / consolidate | 在这个 crate 里加 LLM 客户端 |

隔离靠 project_id。同一个文件上的两个会话不会串味。

DeepSeek Harness（展示）

预期的消费者 / 展示是 DeepSeek Harness：一个薄薄的 Cordis apply(ctx) 插件，架在这个 Rust crate之上（SQLite 留在这里；我们不会用 JS 重写记忆，也不推销自动 LLM 抽取）。

安装命令和验证步骤：安装到 DeepSeek Harness / docs/INSTALL_DSH.md。

- 背书 / 架构：INTEGRATION_DSH.md · 集成说明（中文）
- 宿主实现：integrations/dsh-ai-memory/（从仓库根目录重新导出）
- 旗舰使用场景：scenarios/dsh-support-agent/（侧边栏 + 计费工单；无头 node …/sim/run.mjs 或真实 dsh plugin add）
- 宿主 API：HostSession + ai-memory CLI；首选桥接是进程内 napi-rs（如果缺少 .node 插件则回退到 CLI）

许可证

以下任一许可证下授权

- Apache License, Version 2.0（LICENSE-APACHE）
- MIT 许可证（LICENSE-MIT）

由你选择。

开发

cargo test
cargo test --features sqlite-vec
cargo test -p ai-memory-node
cargo bench
cargo run --example two_projects
cargo run --example assistant_sim
cargo run --example harness_loop_sim
DSH_AI_MEMORY_SKIP_NATIVE=1 npm test --prefix integrations/dsh-ai-memory
node scripts/check-dsh-bundle.mjs
cargo build --bin ai-memory && npm test --prefix scenarios/dsh-support-agent
node scenarios/dsh-support-agent/sim/run.mjs

仓库根目录的 package.json 只是 dsh bundle。纯 Rust 工作不需要 npm install。如果你确实要跑 npm 脚本并且想跳过编译宿主：DSH_AI_MEMORY_SKIP_NATIVE=1。