AI Agent Long-Term Memory System

The Problem: AI's 'Amnesia' and Context Fragmentation

During a single chat, an AI can remember details from minutes ago, but upon starting a new session, all accumulated experiences, past mistakes, and refined conclusions vanish. This cross-session memory deficit forces developers to repeatedly provide the same contextual cues and working patterns, severely hampering the accumulation of knowledge and the AI's capacity for continuous growth.

How the System Works: A Three-Layer Architecture & Core Loop

This skill provides an open-source, local-first long-term experience notebook for AI, centered on natural language interaction for 'storing' and 'finding' information. The system is built upon three parallel layers:
* Semantic Recall Layer (Core): Uses store/index.db (SQLite) as the authoritative storage source, synchronized with human-readable memories/*.json copies. It supports vector semantic search, structured tagging, hot/cold tiering, and sensitive data interception.
* Behavioral Rules Layer: Allows frequently used or confirmed experiences to be exported as persistent behavioral rules for the AI (e.g., into AGENTS.md), influencing future decisions directly rather than just being queried.
* Lightweight File Layer: An optional mode using plain Markdown files, bypassing the database for users who prefer zero-dependency, simple note-taking.

The system operates on a non-destructive core loop:
1. Deposit: Via the deposit command or by saying “remember this…”, an entry is saved with automatic deduplication and categorization. Conflicting older conclusions are marked as superseded.
2. Recall: Via recall or “find…”, the system performs hybrid semantic/lexical retrieval, with filters for freshness and importance.
3. Reflect: reflect --auto triggers automatic organization, conflict detection, and archival, never actively deleting active memories.
4. Decay: decay --apply demotes long-unaccessed memories to archives, but they can still be retrieved via recall --deep.

Operational Boundaries and Critical Considerations

This is an experience distillation system, not a conversation recorder. It is designed to store refined, structured knowledge. Key caveats before use:
* Recall Quality Depends on Backend: Default lexical matching has limited recall rates. Enabling a semantic backend like fastembed is necessary to achieve ~90%+ accuracy.
* Encryption is High-Risk: If encryption is enabled, loss of the key (AI_MEM_ENCRYPTION_KEY) or recovery code results in permanent, irrecoverable data loss. Always generate and secure a backup via recovery-code --write first.
* The Daemon is an Optional Enhancement: It primarily speeds up recall during hook-triggered “auto-memory” scenarios and is not required for core operation. For manual deposit/recall use, no background process is needed.