Memories with directory grouping and optional frontmatter

[MischaPanch]

Currently memory structure is flat and list_memories just returns the memory names. This is impractical for projects with many memories or for memories where the content isn't easily represented by just the file name.

The solution @opcode81 and I agreed on now is the following:

1. Memories can be in subdirectories, the directory enters the memory name. So we can have the list of names like global_mem, auth/login_logic, auth/token_verification
2. Write memory can receive a name with a "/" and will then write to the respective subdir
3. Memories can have frontmatter, which is at the top of the markdown file, between two lines with ---. The frontmatter for now will only contain summary: .... or be empty or missing.
4. list_memories returns memory names and any non-empty frontmatter that was found as answer to the agent.
5. list_memories can receive a path (optionally, by default "", and the kwarg should be called something like topic) and then only lists the memories in that subdir
6. The tool docstrings are adjusted to make the agent group relevant memories together in subdirs (semantically into topics, arbitrary nesting) and write frontmatter if necessary. The agent is also encouraged to structure existing memories and to add frontmatter to them if appropriate.

I think for restructuring existing memories, we should add a new tool RenameMemoryTool, a renaming to something with "/" will then move the file - @opcode81 do you agree?

[MischaPanch]

Related to #737 #994

[MischaPanch]

@keerpawan @simone-viozzi @EarthmanWeb @bguidolim FYI

[opcode81]

I think for restructuring existing memories, we should add a new tool RenameMemoryTool, a renaming to something with "/" will then move the file - @opcode81 do you agree?

@MischaPanch sounds good to me.

[bguidolim]

Having directory grouping + frontmatter is a nice addition, but it's more useful for humans navigating the file tree than for LLMs making read decisions.

The LLM still has to guess whether a memory is worth reading based on frontmatter quality, which depends on whoever wrote it being consistent and descriptive. In practice, summaries tend to be vague or missing, especially as memories accumulate organically.

Even with good frontmatter, a project with 50+ memories still returns a large list that the LLM has to scan and reason over before making any read calls. The cognitive load shifts from "read everything" to "evaluate every summary", still O(n) token burn.

The optional path filter helps if you already know which directory is relevant, but that's circular: to know which directory to look in, you need context about how memories were organized. A new conversation has no such context, so the LLM either scans all directories anyway or makes an educated guess and potentially misses relevant memories elsewhere.

Semantic search solves this at the retrieval layer. Instead of presenting the full list, it returns the top-k most relevant snippets directly. Directory grouping and frontmatter are complementary as organization tools and embedding metadata, but they don't replace semantic search for large memory collections. I'd still love to see #994 move forward.

[Meh10t]

Hi @MischaPanch,

Thank you for suggesting #1055. I’m the student who was going to work on the previous issue #1052, and I’m happy to contribute to this one instead.

It looks interesting and well specified, so I’ll start working on it soon.

Thanks again!

[EarthmanWeb]

I have been encouraging the LLM to use LSP to parse the markdown with the symbols tools, however, it needed some tweaking which I have done in my customized fork.

Now I have it so that my LLM also has the directive to add the symbols listing of related memories at the top of each "Feature" memory as a sort of Index.

It's working very well in my use case, because I'm using it with my very opinionated workflow plug-in Serena-Workflow-Engine

In that fork, I've also improved previously buggy PHP parsing with the LSP

[MischaPanch]

@bguidolim I'm not proposing this as replacement of semantic search, which will be addressed separately. Just pinged you b/c I thought you'd be interested, and there is a minor overlap between semantic search and this.

For many practical cases, a frontmatter summary and name will be good enough though.

[MischaPanch]

@EarthmanWeb

In that fork, I've also improved previously buggy PHP parsing with the LSP

Could you make an issue or directly open a PR on that? Would appreciate it :)

As to the other part - this PR makes a small and very simple step towards more organized memories. We are generally considering various ideas that go beyond that, including more structured frontmatter, using the markdown lsp and so on. For now, we prefer being conservative as we see users having very different opinions about how structured/simple the memory system should be. This step should be a quality of life improvement for essentially all users. Other extensions, while possibly worthwhile, are out of scope for this particular issue.

[bguidolim]

For now, we prefer being conservative as we see users having very different opinions about how structured/simple the memory system should be.

Talking about this, can this feature be opt-in? Or at least have the option to turn off?

[EarthmanWeb]

@MischaPanch Could you make an issue or directly open a PR on that? Would appreciate it :)

Sure, it's kind of all mashed together now, but I'll see if I can get my LLM to break those bits apart into a separate branch

Are you interested in the updates so that it properly parses the markdown headers, as well? It wasn't doing that either.