memory-build-workflow git:20260606.19c883cA

Immutable. This exact content is served forever at /api/v1/blob/b9e3997e1af23e17.

---
name: memory-build-workflow
description: Use when a user needs to build or refresh persistent graph memory from a mixed corpus and the right path may include graphify, incremental update, or helper conversion before ingestion.
---

# Memory Build Workflow

## Overview

Build persistent graph memory with `graphify`.

Use helper tools only when source format would otherwise reduce graph quality or waste context.

## When to Use

- first graph build for a repo, notes folder, research corpus, or mixed raw folder
- corpus changed enough that persistent graph memory is worth refreshing
- input includes PDFs, Office docs, or noisy web pages that should be normalized before graph build
- user wants durable graph outputs instead of one-shot file reading

Do not use for:
- one small plain-text file or a narrow one-off question
- cases where an existing graph already answers the question better via query

## Required Checks

```powershell
apx check graphify
apx check markitdown-file-intake
apx check defuddle
```

Stop and report missing tools. Do not auto-install without approval.

## Routing

| Situation | Action |
|---|---|
| ready local corpus of readable files | run `graphify` |
| existing graph plus changed sources | run `graphify --update` |
| PDF, Office doc, slide deck, or similar hard-to-read format | convert with `markitdown-file-intake`, then build with `graphify` |
| article or noisy web page | clean with `defuddle`, then build with `graphify` |
| user wants vault browsing after build | offer optional Obsidian export |

## Core Rules

- `graphify` is the primary engine
- prefer `graphify --update` over full rebuild when a graph already exists
- use helpers only to improve source readability before graph ingestion
- keep Obsidian optional and post-build
- keep source provenance intact when converting inputs

## Minimal Workflow

1. Check whether a usable graph already exists.
2. If it exists and sources changed, prefer `graphify --update`.
3. If sources are noisy or binary, normalize them with the narrowest helper.
4. Build or refresh with `graphify`.
5. Offer query workflow next instead of rereading the corpus.

## Common Failure Modes

- missing `graphify`: stop and report; no fallback build path
- rebuilding from scratch when update would work: unnecessary cost and churn
- using helpers on already-readable Markdown or code: wasted step
- treating Obsidian as required: wrong; it is optional output only

## Verification

- [ ] Required tool checks ran; missing tools were reported, not auto-installed
- [ ] An existing usable graph was checked for before any build
- [ ] Incremental update was preferred over full rebuild when a graph existed
- [ ] Helpers were used only on sources that would otherwise degrade graph quality
- [ ] Source provenance survived any conversion; Obsidian was offered, never assumed

## References

- [`../graphify/UPSTREAM.md`](../graphify/UPSTREAM.md)
- [`../../references/HELPER_TOOLS.md`](../../references/HELPER_TOOLS.md)
- [`../../references/OBSIDIAN_EXPORT.md`](../../references/OBSIDIAN_EXPORT.md)