FlowMem

Transform any codebase into a rich, navigable Mermaid memory system. Every feature, architecture decision, API flow, and data model becomes a .mmd chart — readable by humans in VS Code, browsable in the generated HTML viewer, and traversable by AI without custom tooling.

When FlowMem is Triggered

Detect which mode by checking whether .flowmem/INDEX.md already exists:

1. Generate — Build a fresh FlowMem memory for a new or existing repo
2. Refresh — Re-run scripts and regenerate stale charts
3. Traverse — Navigate existing .flowmem/ memory to answer questions
4. View — Open or rebuild .flowmem/index.html for visual browsing

Mode 1: Generate (no .flowmem/ exists yet)

Phase 1 — Classify

Read these in order to understand the project:

1. README.md (or README.rst, README.txt)
2. Top-level directory listing (find . -maxdepth 2 -type f)
3. Main source directory (src/, lib/, app/, or equivalent)
4. Any package.json, pyproject.toml, Cargo.toml, go.mod

Then decide which chart types are relevant. Use this selection matrix:

Always generate at minimum:

• structure/modules.mmd (flowchart — file/import dependencies)
• quality/debt.mmd (mindmap — TODO/FIXME map)
• project/overview.mmd (C4Context or flowchart — system overview)

Phase 2 — Extract (Script-backed charts)

Copy all scripts from the skill's scripts/ directory into .flowmem/scripts/ first, then run them.

Scripts to run:

# Python projects
python3 .flowmem/scripts/scan_ast.py > .flowmem/.cache/ast.json
python3 .flowmem/scripts/scan_imports.py > .flowmem/.cache/imports.json
python3 .flowmem/scripts/scan_todos.py > .flowmem/.cache/todos.json
python3 .flowmem/scripts/scan_metrics.py > .flowmem/.cache/metrics.json

# Node/TS projects
node .flowmem/scripts/scan_packages.js > .flowmem/.cache/packages.json
node .flowmem/scripts/scan_ts_exports.js > .flowmem/.cache/ts_exports.json

# Any project (git + filesystem)
bash .flowmem/scripts/scan_git.sh > .flowmem/.cache/git.txt
bash .flowmem/scripts/scan_files.sh > .flowmem/.cache/files.txt

Create .flowmem/.cache/ to hold raw script output. Add .flowmem/.cache/ to .gitignore.

Phase 3 — Chart Generation

For each chart, generate the .mmd content using this structure:

%%{init: {'theme': 'default'}}%%
%% FlowMem | type=<TYPE> | layer=<LAYER> | method=<script|ai> | refresh=<script_path_or_none> | last-updated=<DATE> %%
<DIAGRAM_TYPE>
    ...diagram content...

Layer assignments:

• structure — code organization, dependencies, class hierarchy
• behavior — sequences, state machines, execution flows
• data — schemas, entity relationships, data models
• project — timelines, roadmaps, kanban, requirements
• quality — tech debt, coverage, complexity metrics

Generating script-backed charts: Read the JSON from .flowmem/.cache/ and synthesize into Mermaid syntax.

Example — classDiagram from ast.json:

classDiagram
    class UserStore {
        +login(email, password) bool
        +logout() void
        +currentUser User
    }
    UserStore --> AuthService : uses

Generating AI-backed charts: Reason about the codebase from what you've read. Be specific — name real functions, modules, and concepts from the project rather than using generic placeholders.

Phase 4 — Index Generation

Create .flowmem/INDEX.md:

# FlowMem Index — <project-name>
Generated: <date>

## Structure Layer
| Chart | Type | Method | Description |
|-------|------|--------|-------------|
| [modules.mmd](charts/structure/modules.mmd) | flowchart LR | script | Module import dependency graph |
| [classes.mmd](charts/structure/classes.mmd) | classDiagram | script | Class/interface hierarchy |

## Behavior Layer
...

## Data Layer
...

## Project Layer
...

## Quality Layer
...

## How to use this memory
1. For architecture questions: read `structure/` charts first
2. For API/flow questions: read `behavior/` charts
3. For data model questions: read `data/` charts
4. For planning context: read `project/` charts
5. To refresh stale charts: run `.flowmem/scripts/refresh_all.sh`
6. To view charts visually: open `.flowmem/index.html` in a browser
7. To regenerate AI charts: re-trigger FlowMem with "regenerate charts"

Create .flowmem/TRAVERSE.md from the template in templates/TRAVERSE.md.tmpl, customized with this project's actual chart names and key entry points.

Phase 5 — Finalize

1. Copy all scripts from skill's scripts/ into .flowmem/scripts/
2. Create .flowmem/.gitignore containing .cache/
3. Report to user:
   • Number of charts generated, by layer
   • How to view: open .flowmem/index.html (browser viewer, no install needed)
   • VS Code: install Mermaid Preview extension, open any .mmd file
   • How to refresh: bash .flowmem/scripts/refresh_all.sh

Phase 5b — HTML Viewer Generation

After all .mmd files are generated, create .flowmem/index.html — a self-contained browser viewer that renders every chart using the mermaid.js CDN. This requires NO installation.

Structure of the generated HTML viewer:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>FlowMem — {PROJECT_NAME}</title>
  <script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
  <style>
    /* Blue/white theme — clean, readable */
    body { font-family: Inter, sans-serif; background: #f0f7ff; color: #111827; margin: 0; }
    nav { background: #1e40af; color: white; padding: 0 24px; height: 56px; display: flex;
          align-items: center; justify-content: space-between; position: sticky; top: 0; z-index: 10; }
    .nav-title { font-weight: 700; font-size: 18px; }
    .nav-meta { font-size: 13px; opacity: 0.8; }
    .toc { width: 220px; flex-shrink: 0; padding: 24px 16px; }
    .toc-layer { font-weight: 600; color: #1e40af; font-size: 12px; text-transform: uppercase;
                 letter-spacing: .08em; margin: 16px 0 6px; }
    .toc a { display: block; font-size: 13px; color: #374151; text-decoration: none;
             padding: 4px 8px; border-radius: 6px; margin: 2px 0; }
    .toc a:hover { background: #dbeafe; color: #1e40af; }
    .main { flex: 1; padding: 32px; max-width: 960px; }
    .layer-section { margin-bottom: 48px; }
    .layer-title { font-size: 20px; font-weight: 700; color: #1e40af; border-bottom: 2px solid #bfdbfe;
                   padding-bottom: 8px; margin-bottom: 24px; }
    .chart-card { background: white; border: 1px solid #bfdbfe; border-radius: 12px;
                  margin-bottom: 24px; overflow: hidden; }
    .chart-header { background: #eff6ff; padding: 12px 20px; display: flex; align-items: center;
                    gap: 12px; border-bottom: 1px solid #bfdbfe; }
    .chart-name { font-weight: 600; color: #1e3a8a; font-size: 15px; }
    .badge { padding: 2px 10px; border-radius: 9999px; font-size: 11px; font-weight: 600; }
    .badge-script { background: #dbeafe; color: #1e40af; }
    .badge-ai { background: #ede9fe; color: #5b21b6; }
    .badge-layer { background: #f0fdf4; color: #15803d; }