Memory Conventions and Maintenance
Relevant source files
The following files were used as context for generating this wiki page:
Serena utilizes a "durable memory" system designed to store project-specific information that agents can consult across different sessions. This system relies on progressive discovery through a graph of interlinked memory files, adhering to strict naming and content conventions to ensure long-term utility and referential integrity.
Sources: src/serena/resources/memory_maintenance.md:3-8, src/serena/resources/config/prompt_templates/simple_tool_outputs.yml:8-12
Core Discovery Model
The memory system is architected as a directed graph where mem:core serves as the primary entry point. Project information is distributed across focused memories, grouped by topics or modules (e.g., frontend/core, backend/core).
Navigation and References
Agents discover relevant information by following references within memory files. A valid reference must use the mem: prefix inside backticks, such as `mem:frontend/core`. The referring text is responsible for providing context and guidance on when to consult the linked memory.
Sources: src/serena/resources/memory_maintenance.md:5-15, src/serena/memories/memory_reference_analysis.py:28
Memory Hierarchy Diagram
The following diagram illustrates the relationship between different memory types and the discovery flow:
This diagram shows the progressive discovery from the core entry point to module-specific or technical memories.
Sources: src/serena/resources/config/prompt_templates/simple_tool_outputs.yml:16-32, src/serena/resources/memory_maintenance.md:5-10
Content Conventions
To maintain a high signal-to-noise ratio, memories must follow specific style and update thresholds.
Style and Tone
- Density: Prefer terse bullets and invariants over prose.
- Agent-Focused: Write notes for agents, not documentation for humans.
- Durability: Focus on generalizable guidance rather than task-specific notes.
- Exclusions: Avoid obvious context, rationale, or volatile line-level details.
Sources: src/serena/resources/memory_maintenance.md:19-22
Addition and Update Thresholds
Information should only be committed to memory if it represents a stable, non-obvious project convention.
| Category | Keep in Memory | Exclude from Memory |
|---|---|---|
| Stability | Stable conventions | Volatile details, temporary task notes |
| Complexity | Non-obvious knowledge | Obvious context, generic language facts |
| Scope | Project-wide invariants | One-off facts, quick-read snippets |
Sources: src/serena/resources/memory_maintenance.md:24-26
Memory Management Tools
Serena provides several tools and CLI commands for interacting with the memory system.
Tooling Interface
The system includes specialized tools for reading, writing, and refactoring memories.
This sequence highlights the automated propagation of references when a memory is renamed.
Sources: src/serena/tools/memory_tools.py:10-74, src/serena/memories/memory_manager.py:317-338
Key Management Functions
| Function/Tool | Description | File Source |
|---|---|---|
WriteMemoryTool | Writes UTF-8 encoded Markdown to project or global memory. | memory_tools.py:10 |
ReadMemoryTool | Loads content from a specific memory. | memory_tools.py:40 |
RenameMemoryTool | Renames memory and automatically updates mem: references. | memory_tools.py:59 |
check (CLI) | Validates referential integrity and identifies stale links. | cli.py:1085 |
auto-prefix-references | Heuristically adds mem: to bare memory names in text. | cli.py:1127 |
Referential Integrity and Analysis
The MemoryReferenceAnalyzer handles the logic for detecting broken links and suggested references.
Reference Matching Logic
The system identifies references using the regex pattern (?<![A-Za-z0-9_\-/])mem:([A-Za-z0-9_\-/]+?)(?![A-Za-z0-9_\-/]). This ensures that references are not accidentally matched if they are part of a longer string.
Sources: src/serena/memories/memory_reference_analysis.py:165-172, src/serena/memories/memory_manager.py:134-142
Similarity Scoring
When a reference is "stale" (points to a non-existent file), the system computes similarity scores to suggest candidates.
| Factor | Scoring Logic |
|---|---|
| Exact Match | 1.0 (after normalization) |
| Basename Match | High score; modified by topic prefix similarity |
| Containment | 0.5 + (0.5 * length ratio) if one name contains the other |
| Typos | SequenceMatcher ratio (capped by floors) |
Sources: src/serena/memories/memory_reference_analysis.py:90-136
Integrity Reports
The serena memories check command generates a report identifying:
- Stale References: Broken
mem:links with suggested candidates. - Unmarked References: Bare names in text that match existing memories but lack the
mem:prefix. - Fuzzy Near-Misses: Long tokens that similarity-match memories but aren't exact matches.
Sources: src/serena/memories/memory_reference_analysis.py:270-300, src/serena/cli.py:1113-1123
Conclusion
Memory maintenance in Serena is a balance between automated referential integrity and human-curated dense information. By following the conventions of using mem:core as a root and adhering to the style of dense agent notes, the memory system remains a durable resource for information discovery within complex codebases.
Sources: src/serena/resources/memory_maintenance.md:3-31, src/serena/memories/memory_manager.py:339-354