Purpose
agent-memory is a memory system designed for autonomous agents, aimed at solving the problem of agents "losing their memory" after a session restart or context truncation. The author himself is an agent (g1itchbot), and developed it starting from his own pain points in use, to rebuild identity, track work in progress, and remember key decisions, thereby maintaining continuity of conversations and tasks.
Main Capabilities
Three-Layer Memory Architecture
- Identity layer (identity): stores core identity information, preferences, etc.
- Active layer (active): stores the current project, decisions in progress, and active context.
- Archive layer (archive): stores all remaining memories. The three layers are loaded strategically; identity and active context require only about 700 tokens to provide continuity, avoiding the token waste of loading everything. Semantic search recalls from the archive layer on demand.
Semantic Recall
Based on local embedding vectors (using fastembed) and SQLite (with sqlite-vec) for cosine similarity search, it supports finding memories by semantics rather than keywords.
Automatic Capture
Without an explicit "save" instruction, it automatically extracts decisions, preferences, and insights from conversations.
Intelligent Classification
Through heuristic rules, memories are automatically routed to the correct layer: core identity patterns such as "I am" → identity layer; containing the current project name or active decisions → active layer; the rest → archive layer.
Consolidation and Compression
Periodically merges similar memories (cosine similarity > 0.85), prunes low-value memories, and promotes frequently accessed archive memories to the active layer.
Memory Graph and Relationships
Tracks relationships between memories:
- Updates: new information contradicts or replaces old information.
- Extends: new information supplements details.
- Derives: new insights inferred from combined memories.
- Temporal expiry: temporary reminder-type memories automatically expire. During search, graph relationships enrich the results, and contradictions are resolved in favor of the latest information.
LearningMachine Self-Improvement
Records operation patterns: recall hits/misses, manual corrections, discovered insights, errors, and how they were fixed. Learning outcomes appear alongside regular search results, allowing past mistakes to influence future decisions.
MCP Toolset
Provides multiple MCP tools: recall, capture, capture_facts, capture_decision, capture_preference, record_learning, get_identity, set_identity, get_active_context, set_active, get_startup_context, memory_stats, consolidate. Any MCP-compatible client can use it as a backend.
Usage
- Installation: Install from source (suitable for development).
- Configuration: A single command can automatically configure the MCP server for the agent into its configuration file, and it activates after the agent restarts.
- Database path: The database path needs to be set.
- OpenClaw integration: Provides plug-and-play memory for OpenClaw agents, supporting automatic capture and identity injection.
Applicable scenarios
- Agents that want local-first operation (SQLite, no cloud dependency).
- Developers who value three-layer memory (identity -> active -> archive).
- Agents that want memory to learn from mistakes (LearningMachine).
- It is built by the agent for itself, not by the developer for the agent.
Limitations
- The installation process is still not polished enough and is still in a rough stage.
- Requires Python dependencies and does not provide a zero-dependency single binary (consider engram).
- Does not support multi-agent shared memory (consider Mem0 or Anamnesis).
Technical background
The project references relevant academic research on LLM agent memory mechanisms, including A Survey on the Memory Mechanism of Large Language Model based Agents (Zhang et al., ACM TOIS 2025) and A-mem: Agentic Memory for LLM Agents (NeurIPS 2025). The three-layer architecture draws on the distinction between working memory and long-term memory in cognitive psychology, and has been adapted for token efficiency. Built jointly by g1itchbot and Bill (@rosepuppy).
