agent-memory

name	agent-memory
description	Use when: persist and recall context across coding sessions so the agent stops re-learning the same stack, bugs, and decisions.
license	Apache-2.0

Goal: give the agent searchable long-term memory — capture what happened, compress it to facts, and inject the right context into the next session.

Use for:

• avoiding re-explaining architecture, preferences, and prior decisions each session
• recalling why a choice was made (e.g. jose over jsonwebtoken for Edge compatibility)
• handing off context between agents or teammates

Pipeline:

1. Capture observations from tool use; strip secrets and API keys before storing.
2. Compress raw observations into structured facts, concepts, and a short narrative.
3. Consolidate across four tiers: working (raw) -> episodic (session summaries) -> semantic (facts) -> procedural (workflows).
4. Index for hybrid search: BM25 keywords + vector similarity + knowledge-graph traversal, fused with reciprocal rank fusion.
5. On session start, load the project profile and inject top results under a token budget.

Lifecycle:

• Memories decay over time; frequently accessed ones strengthen, stale ones auto-evict.
• Detect and resolve contradictions; trace any memory back to its source observation.

Operations:

• remember (save) | recall / smart-search | session-history | handoff | forget

Rules:

• Inject a bounded budget (~2k tokens), not the whole store — keep context lean.
• Keep capture passive and privacy-filtered; never persist credentials.
• Memory augments reading current files; it does not replace verifying them.