Memory Management System
Relevant source files
The following files were used as context for generating this wiki page:
The Memory Management System in Serena is designed to store and manage durable, non-obvious information about a project that AI agents can consult during tasks. It facilitates a progressive discovery model where agents build a graph of knowledge through inter-connected memory files, typically stored in Markdown format.
Sources: src/serena/resources/memory_maintenance.md:3-8, src/serena/memories/memory_manager.py:27-30
Architecture and Components
The system is centered around the MemoryManager, which handles filesystem operations, and the MemoryReferenceAnalyzer, which manages the logical integrity of references between memories.
Core Components
| Component | Description |
|---|---|
| MemoryManager | Handles reading, writing, renaming, and deleting memory files. It manages both project-specific and global memories. |
| MemoryReferenceAnalyzer | Provides heuristics for detecting and ranking references, validating integrity, and performing automated fixes. |
| Memory Tools | MCP-exposed tools (read_memory, write_memory, etc.) that allow agents to interact with the memory system. |
| CLI Commands | Subcommands under serena memories for manual maintenance and inspection. |
Sources: src/serena/memories/memory_manager.py:20-25, src/serena/memories/memory_reference_analysis.py:16-24, src/serena/tools/memory_tools.py:10-15, src/serena/cli.py:843-850
Discovery Model
The system follows a graph-based structure:
- Entry Point: Agents are encouraged to read
mem:corefirst. - Progressive Discovery:
mem:corecontains references to major domains, which in turn reference specific sub-topics. - Folders: Memories can be organized into topics using
/as a separator (e.g.,mem:frontend/core).
Sources: src/serena/resources/memory_maintenance.md:3-16
Memory Manager Logic
The MemoryManager differentiates between project-local memories (stored in .serena/memories) and global memories (shared across projects).
The manager ensures that memory names are sanitized, removing mem: prefixes and .md extensions provided by agents.
Sources: src/serena/memories/memory_manager.py:118-132, src/serena/memories/memory_manager.py:44-50
Reference Propagation
When a memory is renamed, the MemoryManager propagates this change across all other memories to prevent broken links. It uses a specific character class [A-Za-z0-9_\-/] to identify boundaries of memory names.
Sources: src/serena/memories/memory_manager.py:214-225, src/serena/memories/memory_reference_analysis.py:59-60
Reference Analysis and Integrity
The MemoryReferenceAnalyzer identifies issues within the memory graph. It distinguishes between "Stale References" (broken links) and "Unmarked References" (bare text that should be a link).
Similarity Heuristics
The system uses a similarity score (0.0 to 1.0) to suggest targets for broken references.
- Case-insensitive: Names are normalized to lowercase.
- Version Stripping: Suffixes like
_v1or_legacyare ignored during comparison. - Topic Moves: Moving a memory to a topic folder (e.g.,
logintoauth/login) results in a 1.0 similarity score.
Sources: src/serena/memories/memory_reference_analysis.py:78-105
Integrity Report Types
| Feature | Logic |
|---|---|
| Stale Reference | A mem:NAME tag where NAME does not exist on disk. |
| Exact Unmarked | Bare text verbatim matching an existing memory name. |
| Fuzzy Near-miss | Long tokens (>=10 chars) matching a memory name but requiring manual review. |
Sources: src/serena/memories/memory_reference_analysis.py:230-264
Tooling and Interaction
Agent Tools
Serena provides a set of tools for agents to manage the memory lifecycle:
- WriteMemoryTool: Writes UTF-8 encoded Markdown content.
- ReadMemoryTool: Retrieves content by name.
- RenameMemoryTool: Renames a file and triggers reference propagation.
- EditMemoryTool: Performs regex or literal replacements within a memory.
Sources: src/serena/tools/memory_tools.py:11-100
CLI Operations
Users can perform maintenance via the serena memories CLI:
serena memories check: Reports stale references and unmarked mentions.serena memories auto-prefix-references: Automatically converts bare text intomem:NAMElinks for high-confidence matches.
Sources: src/serena/cli.py:996-1015, src/serena/cli.py:1034-1052
Web Dashboard
The web dashboard provides a GUI for memory management, allowing users to:
- Create new memories via a modal.
- Edit memory content with a dedicated editor.
- Rename memories with live validation against the supported character set.
Sources: src/serena/resources/dashboard/dashboard.js:1062-1130, src/serena/resources/dashboard/index.html:268-285
Conclusion
The Memory Management System serves as the "long-term memory" for Serena agents. By enforcing a strict reference syntax (mem:) and providing automated tools for discovery and maintenance, it ensures that project-specific conventions and architecture stay durable as different agents work on the codebase.
Sources: src/serena/resources/memory_maintenance.md:21-25, CLAUDE.md:1-4