ai-memory
Open source local Rust + SQLite memory for agent harnesses (pi, Claude-like, Codex-like). You keep the model loop. This crate stores working / episodic / profile notes per project and packs a token-budgeted slice for the next call.
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):
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.
License
Licensed under either of
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.
