From 2b52dd7636b9390b3ed97c8b952fea658bf13c93 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Thu, 14 May 2026 23:48:33 +0200 Subject: [PATCH] Improve memory management documentation and memory terminology * Improve memory_maintenance memory * Drop "routing" terminology, use "references" instead --- .serena/memories/memory_maintenance.md | 47 ++++++++----------- CHANGELOG.md | 12 ++--- docs/02-usage/040_workflow.md | 2 +- docs/02-usage/045_memories.md | 16 +++---- .../prompt_templates/simple_tool_outputs.yml | 4 +- src/serena/resources/memory_maintenance.md | 47 ++++++++----------- 6 files changed, 55 insertions(+), 73 deletions(-) diff --git a/.serena/memories/memory_maintenance.md b/.serena/memories/memory_maintenance.md index cfb4c05c..6f84514d 100644 --- a/.serena/memories/memory_maintenance.md +++ b/.serena/memories/memory_maintenance.md @@ -2,41 +2,32 @@ ## Discovery Model -- Agents start with the full memory name list and should read `mem:core` first as the routing entry point. -- All other memory discovery comes from memory names plus routing already read. -- Routing is useful only before the target memory is selected. Once a memory is open, target-selection text inside it can no longer help decide to read it. -- Therefore, never put self-referential selection cues in a memory body: no "Start here", "Use when", "Use before", "Use after", or "read this when..." openers. - Such self-referential cues are an error mode: they are unreachable for selection, duplicate routing that belongs upstream, and drift independently from the actual routing graph. -- Add routing only when names are insufficient, ambiguous, or a non-obvious dependency/order matters. Do not add tautological routing such as "frontend debugging -> frontend/debugging". -- Routing can live outside core memories when needed, but core memories own most module-level routing because they are read before focused memories in that subfolder. -- Top-level/startup memory is `mem:core`; top-level memory in each memory subfolder is `/core` (for example `mem:frontend/core`). +- Core principle: progressive discovery through references, building a graph of memories. +- Initially, agents are provided with the list of all memories (names only). +- Agents should read `mem:core` as the top-level entry point (graph root). + This memory should contain references to other memories covering major project domains. + The referenced memories shall, in turn, shall contain references to even more specific memories, and so on. + The depth of the graph shall depend on the project complexity. +- Use topics/folders to group related memories in order to make the content structure explicit. + Folders can mirror project structure (e.g. modules like frontend/backend) or topics like debugging, architecture, etc. - Memory references must use a mem: prefix inside backticks, e.g. `mem:frontend/core`. -- Do not add an index that simply re-lists the focused-memory names, the memory name list is already visible. - Only add routing pointers when a target memory's name is not self-explanatory or when a some aspect should be routed to multiple memories. + The surrounding text should clearly indicate when to read the memory/which content to expect. + The text should provide more precise guidance than the memory name alone, + i.e. avoid a reference like "frontend debugging: `mem:frontend/debugging` and instead make clear which aspects of frontend debugging are covered. +- Memories themselves should not contain information about when to read them; this is the responsibility of the referring memory. ## Style -Dense agent notes, not prose docs. Prefer invariants, paths, commands, terse bullets. Avoid obvious context, rationale, and examples unless they prevent likely mistakes. Keep guidance durable and generalizable, not task-local. +Dense agent notes, not prose docs. Prefer invariants, terse bullets. +Avoid obvious context, rationale, and examples unless they prevent likely mistakes. +Keep guidance durable and generalizable, not task-local. ## Add/update threshold -Add or update memory only for stable, non-obvious project conventions that avoid complex rediscovery. - -Do not add: quick-read/rg facts; generic language/framework knowledge; one-off task notes; volatile line-level details; behavior likely to change soon. - -Operational constants (commands, paths, version pins): phrase as current behavior; before changing the value, update it in the owning memory and run `serena memories check` to catch references that need updating. - -## Graph Ownership - -- Project-level routing: `mem:core`. -- Module-level routing/source maps: module core memories. -- Focused memories: topic details only; assume relevant routing was read before selection. +Add or update memories only with stable, non-obvious project conventions that avoid complex rediscovery in the future. +Do not add: quick-read facts; generic language/framework knowledge; one-off task notes; volatile line-level details; behavior likely to change soon. ## Maintenance Actions -- Renamed/removed/split/merged/superseded memory: update all references. Done automatically if handled via Serena's memory rename tool. -- Stale paths/namespaces/commands/behavior: update or remove in owning memory. If working with Serena, call `serena memories check` for a report. -- Split catch-all memory when sections are commonly needed independently or agents must read unrelated domains to reach needed topic. -- Retire/delete memory when owning module/subsystem is removed or replaced; remove all references. -- Added/renamed/split/moved/deleted memory: update affected routing only where names are insufficient. -- Before finishing: list memories for old names and key new names to catch stale/missing references. \ No newline at end of file +- Renaming memories: References are updated automatically if handled via Serena's memory rename tool. +- Checking for stale memories (e.g. after deletion): Call `serena memories check` for a report. \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 47046db5..e22f5712 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,13 +11,13 @@ Status of the `main` branch. Changes prior to the next official version change w - Add Language: replace the native `