ai-memory

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

Local Rust + SQLite memory for agent harnesses: per-project working / episodic / profile notes, and a token-budgeted pack for the next model call (not the full transcript). Optional DeepSeek Harness plugin.

It does not stuff a 1M-token transcript into the prompt, run consolidate in the background, or talk to an LLM.

Install into DeepSeek Harness

Copy-paste guide (pin commit, allowBuilds, what you should see):

• English: docs/INSTALL_DSH.md
• 中文: docs/INSTALL_DSH.zh-CN.md

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

Get <commit> with git ls-remote https://github.com/zzjzzb/ai-memory.git refs/heads/main (left column). After add: dsh --profile web --dump-config must show # == dsh-ai-memory.

Root package.json is the dsh bundle (npm name dsh-ai-memory). Cargo.toml is the Rust crate (package name ai-memory). Same repo, two manifests, not two products.

Docs: USAGE (EN) · 用法 (中文) · ARCHITECTURE (EN) · 架构 (中文) · DeepSeek Harness (EN) · DeepSeek Harness（中文）

Flagship dsh demo: SME support / ops scenario · 中文 — one long session, budgeted pack, not a JS memory rewrite.

Contribute: CONTRIBUTING.md · 参与贡献 · Issues · Pull requests

Scenario → call → get

One long session, many related tickets, chat bigger than the model (~1M or smaller): store each turn, then prefetch_within_budget. Pins and high-score hits fill a 2k–32k token pack (ceil(chars/4) by default).

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()?;  // optional, explicit TTL + promote
    Ok(())
}

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

open() applies WAL and other SQLite defaults. Inject a real Embedder when you have one; default HashEmbedder is offline. Optional --features sqlite-vec.

Do / don't

Do	Don't
Persist turns with remember_turn	Dump the full transcript into the model
prefetch_within_budget(query, TokenBudget { max_tokens })	Expect 1M tokens to fit in one prompt
pin must-keep facts	Auto-consolidate or auto-compact
Call compact_working / consolidate when you mean to	Add an LLM client in this crate

Isolation is project_id. Two sessions on one file do not leak recall.

DeepSeek Harness (showcase)

The intended consumer / showcase is DeepSeek Harness: a thin Cordis apply(ctx) plugin over this Rust crate (SQLite stays here; we do not rewrite memory in JS, and we do not pitch auto-LLM extraction).

Install command and verify steps: Install into DeepSeek Harness / docs/INSTALL_DSH.md.

• Endorsement / architecture: INTEGRATION_DSH.md · 集成说明（中文）
• Host implementation: integrations/dsh-ai-memory/ (re-exported from the repo root)
• Flagship usage scenario: scenarios/dsh-support-agent/ (sidebar + billing tickets; headless node …/sim/run.mjs or real dsh plugin add)
• Host API: HostSession + ai-memory CLI; preferred bridge is in-process napi-rs (CLI fallback if the .node addon is missing)

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

Develop

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 at the repo root is only the dsh bundle. Rust-only work does not need npm install. If you do run npm scripts and want to skip compiling the host: DSH_AI_MEMORY_SKIP_NATIVE=1.