Contributing to ai-memory

Thanks for helping. This crate is a local memory layer for agent harnesses — not an LLM client and not a cloud sync product.

中文版：CONTRIBUTING.zh-CN.md

Quick start

git clone https://github.com/zzjzzb/ai-memory.git
cd ai-memory
cargo test
cargo run --example harness_loop_sim

Optional vector extension tests:

cargo test --features sqlite-vec

How to contribute

1. Open an issue for bugs or design discussion (preferred before large changes).
2. Fork the repo and create a branch from main.
3. Keep changes focused. Prefer boring, maintainable Rust.
4. Add or update tests for behavior you change. cargo test must stay green.
5. Update docs when you change public API or the recommended harness pattern:
   • docs/USAGE.md / docs/USAGE.zh-CN.md
   • docs/ARCHITECTURE.md / docs/ARCHITECTURE.zh-CN.md
   • DeepSeek Harness showcase: docs/INSTALL_DSH.md / docs/INSTALL_DSH.zh-CN.md, docs/INTEGRATION_DSH.md / docs/INTEGRATION_DSH.zh-CN.md, integrations/dsh-ai-memory/ (DSH_AI_MEMORY_SKIP_NATIVE=1 npm test there; node scripts/check-dsh-bundle.mjs at repo root), and the flagship scenario scenarios/dsh-support-agent/ (cargo test --test dsh_support_scenario)
6. Open a pull request against main with a short description of why.

Design boundaries (please respect)

In scope

• Project-scoped memory, MemoryPolicy, hybrid recall, harness adapter (AgentSession, HostSession, tools, budgeted ContextPack)
• Thin DeepSeek Harness Cordis plugin that calls this crate (napi or CLI — not a JS store)
• Usage scenarios that drive that plugin (headless sim + documented dsh plugin add)
• Transparent local performance (SQLite defaults, caches, prune)
• Offline-first defaults (no network required for tests)

Out of scope (unless discussed in an issue first)

• Building a full LLM harness / vendor SDK (pi, Claude, Codex, DeepSeek clients)
• Multi-device sync or hosted multi-tenant cloud
• Background auto-consolidate or silent policy changes
• Stuffing full transcripts into the model prompt (use prefetch_within_budget)

Code style

• Match existing module layout (store, sqlite, harness, …).
• Public API should stay easy for SME developers: good defaults, few knobs.
• Do not add heavy dependencies without a clear win.

License

Dual-licensed under MIT OR Apache-2.0. Contributions are accepted under the same terms.