memory-build-workflow

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

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
• ../../references/HELPER_TOOLS.md
• ../../references/OBSIDIAN_EXPORT.md