Skip to article content

Revised 23 October 2026 · v1.0.0 · what changed

Code: github.com/herrrickshaw/memory-map-optimizer

Watch the walkthrough

Watch on YouTube: youtu.be/olyhzUrn_0c

Why it is useful

• Who benefits: people who keep a large pile of markdown notes or an AI-assistant memory folder and a graph of how things link, and want structure and duplicates found automatically.
• What it replaces: counting and merging near-identical notes by hand, and a graph tool whose community detection returned zero.
• Evidence from the run: on a synthetic 60-node graph with three planted groups, the cluster command found exactly three communities of 20 nodes each in 0.14 seconds; all 14 bundled checks passed.
• The embedding, search and dedup steps need a downloaded model of about 1.5 GB and were not run here (see limits).

What it is for

The tool has five commands. cluster runs Leiden community detection on a graph JSON with nodes and edges. embed indexes markdown files with a sentence-embedding model. search combines keyword (BM25) and embedding ranks, with an optional reranker. dedup groups near-duplicate files by cosine similarity. report writes an HTML overview.

It was written for one person's Claude Code memory setup, so default paths point at ~/.graphify and ~/.claude. Pass your own paths to use it elsewhere.

Who it is for

• People maintaining a large markdown notes or memory folder
• Developers who want a small, readable example of Leiden clustering and hybrid search
• Non-programmers who want an AI assistant to run it on their notes

What you need

Get the code and an AI assistant

You do not have to be a programmer. Get the repository, give it to an AI assistant, and ask in plain language. Any of these routes works:

git clone https://github.com/herrrickshaw/memory-map-optimizer.git
cd memory-map-optimizer
claude      # or: gemini

Install

1. Get the code

   git clone https://github.com/herrrickshaw/memory-map-optimizer.git
   cd memory-map-optimizer

2. Create an environment and install

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

Quick start: commands and what you should see

Run the bundled checks

python test_memory_map_optimizer.py

A line per check ending in ALL TESTS PASSED.

Cluster a graph file

python memory_map_optimizer.py cluster --graph my_graph.json --write-back --out clusters.json

A line such as '60 nodes, 213 edges -> 3 communities (modularity 0.6082)' and a size per cluster.

Index, search and dedupe notes (needs the model download)

python memory_map_optimizer.py embed --memory-dir "./notes/**"
python memory_map_optimizer.py search "token routing" --rerank
python memory_map_optimizer.py dedup --threshold 0.85

An index file, ranked results, and groups of near-duplicate files.

Sample outputs

Real output from a run on the date shown in the sources line; trimmed to fit.

Bundled checks

python test_memory_map_optimizer.py
test_leiden_finds_real_communities OK (4 communities found, planted 4, modularity 0.721)
test_hybrid_search_ranks_relevant_doc_first OK
test_find_duplicate_groups_merges_transitively OK
test_report_runs_without_index_or_clusters OK
ALL TESTS PASSED

Trimmed to four of 14 lines. The search and dedup checks use hand-built vectors, not a real model.

Cluster command on a synthetic memory map

python memory_map_optimizer.py cluster --graph g.json --write-back --out clusters.json
60 nodes, 213 edges -> 3 communities (modularity 0.6082)
  cluster 2: 20 nodes
  cluster 0: 20 nodes
  cluster 1: 20 nodes
wrote clusters.json
wrote community assignments back into g.json

The graph was random: 60 nodes in three groups of 20, dense inside each group (35 percent of node pairs linked) and sparse between them (1 percent). The tool recovered the planted groups exactly.

What the output file looks like

{ "num_nodes": 60, "num_edges": 213, "num_clusters": 3, "modularity": 0.6082,
  "cluster_sizes": {...}, "node_to_cluster": {"n0": 2, "n1": 2, ...} }

Each node also receives a 'community' field in the graph JSON when --write-back is set.

embed, search, dedup, report with a real model

Not run. These need sentence-transformers plus a roughly 1.5 GB model download.

The README itself says embed was never confirmed end to end in its build sandbox.

Ways to use it

Sample prompts for your AI assistant

Copy, paste and edit the parts in [brackets].

• Claude: Read memory_map_optimizer.py and explain how the hybrid BM25 plus embedding ranking is combined.
• Gemini: Build a small graph JSON of 30 nodes in three groups and run the cluster command on it, then explain modularity.
• ChatGPT: Here are my cluster sizes from clusters.json. Which clusters look too big to be useful and why?
• GitHub (Copilot Chat): Add a flag to cluster that prints the three highest-degree nodes in each community, with a test.
• Claude: Run dedup with a sweep on a copy of my notes folder and propose which files to merge, without deleting anything.

Limits and honest caveats

Sources: Ran test_memory_map_optimizer.py and the cluster command on a synthetic graph from a fresh clone of github.com/herrrickshaw/memory-map-optimizer (commit aff6b31) in a throwaway virtualenv on 19 October 2026, installing python-igraph, leidenalg, rank-bm25 and numpy only. Embedding commands not run.

About this article: Researched, written and edited by Umashankar Triplicane Dwarakanathan, with AI research assistance; every figure is meant to trace to the primary source cited. See the Editorial Policy for how sourcing, AI use and corrections work.