Improve memory management documentation and memory terminology

* Improve memory_maintenance memory
* Drop "routing" terminology, use "references" instead

.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 `<folder>/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.
+- 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.

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 `<select>` with a filterable combobox — type to filter, keyboard navigation (Up/Down/Enter/Esc), substring highlight, click-outside to close. The typed value is validated against the available languages list before submission.
 
 * Memories:
-  - Memories can now reference each other using the `` `mem:NAME` `` convention. Renames
+  - Memories can now reference each other using the `mem:<name>` convention. Renames
     propagate to all references automatically. See the [reference convention](https://oraios.github.io/serena/02-usage/045_memories.html#referencing-memories-from-other-memories).
-  - Onboarding now seeds a `memory_maintenance` memory describing the memory-style and
-    routing conventions, and the agent is instructed to read it before writing any other
-    memories. A `global/memory_maintenance` memory takes precedence over the per-project
-    seed. See the [memory maintenance section](https://oraios.github.io/serena/02-usage/045_memories.html#the-memory-maintenance-memory).
-
+  - Onboarding now seeds a `memory_maintenance` memory describing the memory-style and conventions, 
+    and the agent is instructed to read it before writing any other memories. 
+    A `global/memory_maintenance` memory takes precedence over the per-project seed. 
+    See the [memory maintenance section](https://oraios.github.io/serena/02-usage/045_memories.html#the-memory-maintenance-memory).
+   
 * CLI:
   - Add `serena memories` CLI command group: `list`, `read`, `write`, `check` (referential
     integrity report) and `auto-prefix-references` (heuristic rewrite of bare occurrences).

docs/02-usage/040_workflow.md

@@ -148,7 +148,7 @@ are kept in sync across renames, and a `serena memories check` command is availa
 to report stale references.
 
 During the first onboarding, Serena seeds a `memory_maintenance` memory describing the
-conventions (style, references, routing) that subsequent memories should follow, and the
+conventions (style, references) that subsequent memories should follow, and the
 agent is instructed to read it before writing any project-specific memories.
 
 For more information on this, including the target memory layout, the `mem:` reference

docs/02-usage/045_memories.md

@@ -30,15 +30,15 @@ criteria:
 2. **Versionable with the project.** Project memories live alongside the code and can
    be committed, reviewed in PRs, and reverted like any other repository artifact.
 3. **Progressive disclosure.** Agents receive the full memory *name list* up
-   front as part of their initial instructions; any further routing is described inside
+   front as part of their initial instructions; any further references are described inside
    the memory content itself - typically a `mem:core` entry point pointing at focused
-   memories. The agent decides what to read based on names plus the routing it has
+   memories. The agent decides what to read based on names plus the references it has
    already seen.
-4. **Prefer routing to search.** Given an intelligent agent and well-structured routing, search is
+4. **Prefer references to search.** Given an intelligent agent and well-structured references, search is
    unnecessary - and it adds noise: any retrieval method (lexical or semantic)
-   produces both false positives and false negatives. Explicit, name-based routing
-   decided by the agent is deterministic and avoids both error modes. Basic search via regex/grep
-   is sufficient to complement the routing when needed and is available to any agent.
+   produces both false positives and false negatives. Explicit, name-based references
+   decided by the agent are deterministic and avoid both error modes. Basic search via regex/grep
+   is sufficient to complement the references when needed and is available to any agent.
 5. **Prefer deliberate reads to triggers.** The agent decides what to read and when. The harness does
    not inject memory content on the agent's behalf.
 6. **Framework-agnostic.** The storage format is plain Markdown files in
@@ -85,7 +85,7 @@ This convention has two practical consequences:
   not resolve to an existing memory, and propose similarly-named candidates as likely intended
   targets.
 
-The full convention - including style, add/update thresholds, and how to structure routing across
+The full convention - including style, add/update thresholds, and how to structure references across
 `core` memories - is shipped to every onboarded project as the `memory_maintenance` memory; see the
 [Onboarding section](onboarding) below.
 
@@ -158,7 +158,7 @@ process if memories are found.
 To make memory conventions discoverable to both the LLM and the user, Serena seeds
 a `memory_maintenance` memory on first onboarding. The seed is copied from a template
 shipped with the Serena package and contains the dense agent-notes style, the
-`mem:` reference convention, the routing model around `core` memories, the
+`mem:` reference convention, the reference model around `core` memories, the
 add/update threshold, and the maintenance actions (rename / delete / split).
 
 The seeding follows a strict precedence:

src/serena/resources/config/prompt_templates/simple_tool_outputs.yml

@@ -28,8 +28,8 @@ prompts:
       (linter, formatter, test runner, type checker, etc.).
 
     If the project has clearly distinct modules (e.g. frontend/backend), create per-module
-    `mem:<module>/core` memories for module-specific routing instead of pushing everything
-    into `mem:core`.
+    `mem:<module>/core` memories with module-specific references to further memories instead 
+    of pushing everything into `mem:core`.
 
     Acquire information using the available tools. Read only the files needed; do not load
     entire directory trees. If essential information is missing, ask the user.

src/serena/resources/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 `<folder>/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.
+- 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.