From b0695dd4b51b2e6c9b0fb5c23f3dc7d09598d0e3 Mon Sep 17 00:00:00 2001 From: jared Date: Wed, 3 Jun 2026 16:45:07 -0400 Subject: [PATCH] Add Graphify setup & best-practices guide (11 docs + research) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Research: dispatched 11 subagents to synthesize a creator interview into 11 standalone documents (overview, install, code/doc ingestion, backends, querying, token economics, workflows, best practices, and community tips), then reconciled cross-document contradictions against the GitHub repo (v0.8.30 release). Verified all substantive claims against primary sources (GitHub, interview, community, PyPI). Corrected interview errors: package is graphifyy (double-y), shell scripts now AST-supported, Slack/meetings/OneNote connectors are roadmap not shipped. Settled flag version disputes (--token-budget vs. --budget) by grepping raw README bytes. Applied honest token-savings framing (1–49x measured, not 70–90x marketing). Every claim tagged inline by source confidence ([github] / [interview] / [community] / [unverified]). Zero broken links, zero residual contradictions. Deliverable: docs/graphify/ - 00-README.md: index, reading order, provenance - 01-overview-concepts.md: god nodes, neuro-symbolic, vs. Obsidian - 02-installation-setup.md: install, register, first run - 03-ingesting-code-ast.md: tree-sitter, 33 languages, multi-repo - 04-ingesting-docs-knowledge.md: PDF/media/YouTube/Google Workspace - 05-local-models-and-backends.md: Ollama vs. cloud, privacy - 06-querying-and-god-nodes.md: god-nodes-first discipline - 07-token-economics-and-updates.md: savings honestly, --update, SHA hashing - 08-workflows-and-use-cases.md: onboarding, bug-trace, audits, second brain - 09-best-practices-checklist.md: do/don't reference + quick commands - external-tips.md: community tips, gotchas, savings debate Also included: graphify-interview (raw creator interview, source material), memory-systems-compared060326 (research reference). --- docs/graphify/00-README.md | 92 ++ docs/graphify/01-overview-concepts.md | 118 +++ docs/graphify/02-installation-setup.md | 224 +++++ docs/graphify/03-ingesting-code-ast.md | 202 +++++ docs/graphify/04-ingesting-docs-knowledge.md | 199 +++++ docs/graphify/05-local-models-and-backends.md | 203 +++++ docs/graphify/06-querying-and-god-nodes.md | 231 +++++ .../07-token-economics-and-updates.md | 173 ++++ docs/graphify/08-workflows-and-use-cases.md | 221 +++++ docs/graphify/09-best-practices-checklist.md | 126 +++ docs/graphify/external-tips.md | 100 +++ graphify-interview | 829 ++++++++++++++++++ memory-systems-compared060326 | 326 +++++++ 13 files changed, 3044 insertions(+) create mode 100644 docs/graphify/00-README.md create mode 100644 docs/graphify/01-overview-concepts.md create mode 100644 docs/graphify/02-installation-setup.md create mode 100644 docs/graphify/03-ingesting-code-ast.md create mode 100644 docs/graphify/04-ingesting-docs-knowledge.md create mode 100644 docs/graphify/05-local-models-and-backends.md create mode 100644 docs/graphify/06-querying-and-god-nodes.md create mode 100644 docs/graphify/07-token-economics-and-updates.md create mode 100644 docs/graphify/08-workflows-and-use-cases.md create mode 100644 docs/graphify/09-best-practices-checklist.md create mode 100644 docs/graphify/external-tips.md create mode 100644 graphify-interview create mode 100644 memory-systems-compared060326 diff --git a/docs/graphify/00-README.md b/docs/graphify/00-README.md new file mode 100644 index 0000000..0690971 --- /dev/null +++ b/docs/graphify/00-README.md @@ -0,0 +1,92 @@ +# Graphify — Setup & Best-Practices Guide + +A practical handbook for setting up and using **Graphify** ([safishamsi/graphify](https://github.com/safishamsi/graphify), +PyPI package `graphifyy`) across many projects at once — code, documents, and a personal knowledge base. +Graphify turns a folder of mixed content into a queryable **knowledge graph** that your AI coding assistant +reads instead of re-reading the whole corpus every session. + +The guide is distilled from a creator interview (a marketing/influencer piece — see provenance below), +then verified and corrected against the official GitHub repository and supplemented with independent sources. + +## Read in this order + +1. **[01-overview-concepts.md](01-overview-concepts.md)** — What Graphify is and the mental model: + knowledge-graph-of-everything, god nodes, confidence tags, neuro-symbolic framing, why a graph beats + plain file search and Obsidian. **Start here.** +2. **[02-installation-setup.md](02-installation-setup.md)** — Install (`uv tool install graphifyy`), + register with your assistant, first `graphify .` run, and how to avoid a first-run token blowout. +3. **[03-ingesting-code-ast.md](03-ingesting-code-ast.md)** — Indexing **code** with tree-sitter AST: + free, no LLM, 33 languages, multi-repo. The core rule: *AST for code, save the model for documents.* +4. **[04-ingesting-docs-knowledge.md](04-ingesting-docs-knowledge.md)** — Indexing **documents & a personal + KB**: PDF/docx/xlsx/images, audio/video transcription, YouTube, Google Workspace; when documents need a model. +5. **[05-local-models-and-backends.md](05-local-models-and-backends.md)** — **Backends**: local Ollama/SLM + vs. cloud (Bedrock, Claude, Gemini, OpenAI, …), env vars, privacy, and choosing on cost/quality/privacy. +6. **[06-querying-and-god-nodes.md](06-querying-and-god-nodes.md)** — The highest-leverage skill: + ask for **god nodes first**, then scalpel down; *prompt the graph, don't make the LLM read the corpus.* +7. **[07-token-economics-and-updates.md](07-token-economics-and-updates.md)** — Where savings really come + from (honestly), cost levers, and keeping the graph fresh with `--update` (SHA-256 + dedup) and hooks. +8. **[08-workflows-and-use-cases.md](08-workflows-and-use-cases.md)** — End-to-end playbooks: onboarding, + bug tracing, AI-slop audits, the cross-project "second brain," PR impact analysis. +9. **[09-best-practices-checklist.md](09-best-practices-checklist.md)** — The do/don't reference card + + command quick-reference + setting-up-across-many-projects mini-guide. **Keep this one open while working.** +10. **[external-tips.md](external-tips.md)** — Independent/community tips, gotchas with issue links, and an + even-handed look at the token-savings debate. + +## One-paragraph summary + +Install with `uv tool install graphifyy` (the package is `graphifyy` — double-y, a temporary name — but the +command is `graphify`), then `graphify install` to register it with Claude Code (or Codex/Cursor/Gemini/OpenCode). +Run `graphify .` on a folder; it writes `graphify-out/` containing an interactive `graph.html`, a `GRAPH_REPORT.md` +(whose top lists the **god nodes** — the most-connected concepts), and a `graph.json`. **Code** is parsed locally +with tree-sitter AST — free, no tokens, 33 languages. **Documents, images, and media** need a model backend for +semantic extraction; point that at **local Ollama** to keep it free and private, or at a cloud model. The retrieval +discipline that delivers the savings: ask for god nodes first, then query the graph (`graphify query`/`path`/`explain`) +rather than dumping the whole corpus into context. Always `graphify ... --update` when adding data so it merges +(SHA-256 hashing + dedup) instead of rebuilding. Fold many repos into one graph with `graphify global add`. + +## How this guide was built — provenance & honesty + +This matters because you're going to *run* these commands. Each substantive claim in the docs is tagged inline: + +| Tag | Meaning | +|-----|---------| +| `[github]` | Verified against the official repository README (see version note below) — **most trustworthy** | +| `[interview]` | Stated only in the creator interview — unconfirmed framing or claim | +| `[community](url)` | From an independent third-party source, with link | +| `[site]` / `[pypi]` | From graphifylabs.ai or the PyPI listing | +| `[unverified claim]` | Asserted (often marketing) but not confirmed against a primary source | + +**Sources, and how much to trust them:** + +- **The interview** (`graphify-interview` in the repo root) is a hype/marketing influencer piece with the creator + (Safi Shamsi) and noisy auto-transcription. It's a good source of *intent and workflow advice* but a poor source + of *facts* — names, commands, and numbers are garbled. We treated it as a starting hypothesis, not ground truth. +- **The GitHub repo** is the authority. We anchored on the **v0.8.30 release README** (published 2026-06-02, the + latest published release as of 2026-06-03; a `v1.0.0` tag also exists but isn't a published release). Disputed + flags were settled by grepping the *raw* README bytes, not summaries. +- **The official site** (https://graphifylabs.ai/) returned **HTTP 403** to automated fetches, so nothing was + verified directly from it; site-only claims are flagged. + +**Corrections we made to the interview's claims (and why they're in the docs):** + +- **"AST for code, LLM for documents"** holds — but the interview's claim that **shell scripts aren't AST-supported** + is outdated; v0.8.30 lists `.sh`/`.bash`/`.ps1` among its 33 tree-sitter languages. +- **Package name** is `graphifyy` (double-y), not `graphify`, on PyPI. +- **Flag set is version-dependent.** `--token-budget`, `--max-concurrency`, `--api-timeout`, `--budget`, and + `--force` are all real in **v0.8.30** (grep-verified) but absent from the shorter `main`-branch README. If your + build differs, confirm with `graphify --help`. Note: `--budget` caps *query answer* size; `--token-budget` sets + *extraction* chunk size — different flags, different stages. +- **"Meetings / Slack / OneNote connectors"** are roadmap or belong to a separate product, **not** shipped in + Graphify today. + +**On the headline token-savings numbers (70x / 90x / 71.5x):** treat them as corpus-dependent marketing, not a +guarantee. Independent testing (roborhythms) reproduced large-monorepo wins but measured a realistic **~1–49x**, +with **net-negative** results on small repos (the mandatory "read the graph first" preamble can cost more than it +saves on <100-file projects — see GitHub issue #580). The creator himself says there's "no floor, no ceiling." +**Measure your own with `graphify benchmark`.** (Separately, the repo's *popularity* claims under-sold reality: +third-party trackers showed ~58K stars and ~1.28M downloads as of 2026-06-03 — bigger than the interview's figures.) + +**Caveat — Graphify moves fast.** Multiple releases shipped *per day* during early June 2026. Commands and flags +here reflect v0.8.30; if something doesn't match, run `graphify --help` and prefer the latest release README. + +_Last updated: 2026-06-03 · anchored to Graphify v0.8.30_ diff --git a/docs/graphify/01-overview-concepts.md b/docs/graphify/01-overview-concepts.md new file mode 100644 index 0000000..740f834 --- /dev/null +++ b/docs/graphify/01-overview-concepts.md @@ -0,0 +1,118 @@ +# Graphify: Overview & Mental Model + +Graphify turns any folder — code, documents, and media — into a single queryable **knowledge graph** that your AI assistant reads instead of blindly re-reading raw files. This page is the mental model you need *before* deciding whether to adopt it; the how-to lives in the rest of this set. + +--- + +## The one-line concept + +> "Graphify transforms project folders into queryable knowledge graphs ... it maps your entire codebase — code, documentation, PDFs, images, and videos — into a structured representation you can search and explore." `[github]` + +The pitch is a **knowledge-graph-of-everything**: source code, docs, PDFs, images, and transcribed audio/video all land in *one* graph you can query, rather than living in separate silos that your assistant has to grep through one at a time. The creator (Safi Shamsi) frames it as a "digital brain" / "digital twin" of a codebase or enterprise that you can recall at any time `[interview]`. + +See [02-installation-setup.md](02-installation-setup.md) to get it running and [08-workflows-and-use-cases.md](08-workflows-and-use-cases.md) for concrete scenarios. + +--- + +## Why a graph beats plain file search + +Plain AI coding assistants work on flat files: + +> "AI coding assistants operate on flat-file context. They read files, sometimes many at once, but they have no map of how concepts relate across your codebase." `[community]`([augmentcode](https://www.augmentcode.com/learn/graphify-knowledge-graphs-ai-coding)) + +A graph pre-computes the **relationships** — which function calls which, which doc explains which module, which concepts recur across files. The verified payoff over grep/file-search is *cross-file structure*: + +> "Unlike grep or file search, Graphify understands *relationships* across your codebase ... links between things that live in different files or modules. Ranked by how unexpected they are." `[github]` + +So instead of "find the file named `auth`," you can ask "what connects auth to the database?" and get a path through the graph. Query mechanics are covered in [06-querying-and-god-nodes.md](06-querying-and-god-nodes.md). + +--- + +## Why a graph beats Obsidian + +People reasonably ask: *isn't this just an Obsidian vault graph?* The creator's argument is that Obsidian only *visualizes* links, while Graphify does real graph analysis on top `[interview]`: + +- Obsidian "can't do clustering for you" — it won't group related notes into communities. `[interview]` +- Obsidian "can't do cross-community interaction" — it won't surface links *between* clusters. `[interview]` +- Obsidian's graph "looks pretty much well but there is nothing credible you can take from there." `[interview]` + +Treat those three claims as the creator's framing (unconfirmed), not measured fact. The *verified* version of the same point is milder: Graphify computes ranked "surprising connections" across files/modules `[github]`, which a visualization-only tool doesn't do. In practice Obsidian remains a fine **visual pairing** — the interview itself calls it "a decent recommended pairing because it's visual" `[interview]`. + +--- + +## God nodes + +**God nodes** are the most important hubs in your graph: + +> "the most-connected concepts in your project. Everything flows through these." `[github]` + +Mental model: god nodes are the load-bearing entities — the architecture's spine. The recommended habit is to **ask for god nodes first**, get the high-level map in one shot, then "scalpel" down into specific nodes only where needed (this is the core token-saving move) `[interview]`. The creator also offers a rough diagnostic: an unexpectedly *large* number of god nodes can signal poor cohesion in a codebase `[interview]` (unverified heuristic). Details and example queries: [06-querying-and-god-nodes.md](06-querying-and-god-nodes.md). + +--- + +## Community / cluster detection + +Graphify runs clustering to group related entities into **communities**, with adjustable granularity: + +> "The tool runs clustering to group related entities. You can rerun clustering on existing graph and adjust granularity with resolution parameters." `[github]` + +This is what powers the two things Obsidian reportedly can't do: grouping nodes into communities, and detecting **cross-community links** (relationships that bridge otherwise-separate clusters). Conceptually this is standard graph theory (community detection via clustering algorithms) `[interview]`. The relevant flags (e.g. cluster-only runs and a resolution setting) are documented in [06-querying-and-god-nodes.md](06-querying-and-god-nodes.md) — don't guess at them from here. + +--- + +## Confidence tags: EXTRACTED / INFERRED / AMBIGUOUS + +Every relationship in the graph carries a confidence label, so you know how much to trust it: + +- `EXTRACTED` — "directly found in source" `[github]` +- `INFERRED` — "logically deduced" `[github]` +- `AMBIGUOUS` — "uncertain connections" `[github]` + +Corroborated by community write-ups: "Every relationship gets tagged as `EXTRACTED`, `INFERRED`, or `AMBIGUOUS`, so developers know which connections came from code versus model inference." `[community]`([augmentcode](https://www.augmentcode.com/learn/graphify-knowledge-graphs-ai-coding)) + +The mental-model takeaway: `EXTRACTED` edges come from deterministic parsing (the AST — see [03-ingesting-code-ast.md](03-ingesting-code-ast.md)); `INFERRED`/`AMBIGUOUS` edges come from a language model reading prose. Weight them accordingly when you act on a query result. + +--- + +## The "neuro-symbolic" framing + +The creator positions Graphify as more than a RAG store — as a step toward **neuro-symbolic AI**, where the graph acts as a layer of *symbols* that ground the *neural* network: + +> Graphify "isn't just supporting neural networks, it's giving rise to neuro-symbolic AI systems where you have a map or symbols to support the neural networks to come up with a response." `[interview]` + +The stated motivation: neural networks (LLMs) hallucinate and lose context, especially as you cram more into the context window; a symbolic graph constrains and grounds retrieval, reducing that drift `[interview]`. Neuro-symbolic AI is a genuine research area, but the specific claim that *Graphify* meaningfully reduces hallucination is the creator's pitch — not independently verified here. Treat it as a useful intuition, not a measured result. + +--- + +## The three outputs + +Every run produces three artifacts `[github]`: + +| File | What it is | +|------|-----------| +| `graph.html` | Interactive visualization — "open in any browser — click nodes, filter, search" `[github]` | +| `GRAPH_REPORT.md` | Markdown report — "the highlights: key concepts, surprising connections, suggested questions" `[github]` | +| `graph.json` | The full graph — "query it anytime without re-reading your files" `[github]` | + +The `graph.json` is the durable, reusable asset: it's what lets later queries stay cheap. That cost story (and the incremental-`update` mechanism) is in [07-token-economics-and-updates.md](07-token-economics-and-updates.md). Local-vs-cloud extraction backends are in [05-local-models-and-backends.md](05-local-models-and-backends.md). + +--- + +## How the pieces fit (decision summary) + +- **Code** is parsed locally via tree-sitter ASTs — no API calls, no tokens spent `[github]` `[interview]`. See [03-ingesting-code-ast.md](03-ingesting-code-ast.md). +- **Docs / media** need a language model to extract meaning, so they cost tokens (or run on a local model) `[interview]`. See [04-ingesting-docs-knowledge.md](04-ingesting-docs-knowledge.md) and [05-local-models-and-backends.md](05-local-models-and-backends.md). +- The graph is the **memory/context**; the discipline is "ask the graph, don't make the LLM re-read the corpus" `[interview]`. +- Start from **god nodes**, then drill down — that's where the savings come from `[interview]`. + +For an end-to-end adoption checklist, jump to [09-best-practices-checklist.md](09-best-practices-checklist.md). Index: [00-README.md](00-README.md). + +--- + +## Open questions / unverified + +- **Headline numbers are marketing.** Token savings of "70x"/"90x", "500K downloads," "43K stars" are sales claims and they conflict across sources (e.g. one community post cites 58.3K stars). `[unverified claim]` Do not treat any of these as fact. +- **Neuro-symbolic = less hallucination** for Graphify specifically is the creator's framing `[interview]`, not independently measured. +- **The Obsidian critique** (can't cluster, no cross-community links, "nothing credible") is `[interview]` only; the verified contrast is the narrower "ranked cross-file connections" claim `[github]`. +- **"Large god-node count signals poor cohesion"** is an unverified diagnostic heuristic from the interview. +- **graphifylabs.ai** could not be fetched (HTTP 403 bot protection), so its exact tagline/claims are not directly verified here. diff --git a/docs/graphify/02-installation-setup.md b/docs/graphify/02-installation-setup.md new file mode 100644 index 0000000..d9eb62b --- /dev/null +++ b/docs/graphify/02-installation-setup.md @@ -0,0 +1,224 @@ +# Installation & First Run + +How to install Graphify, register it with Claude Code (and other assistants), run your first graph, and confirm it worked — without accidentally burning through your token/usage limit on the first try. + +> Provenance tags used throughout: `[github]` = official GitHub README (anchored to the **v0.8.30** release README, the comprehensive current version — fetched 2026-06-03; the shorter `main`-branch README omits some flags), `[pypi]` = PyPI page, `[site]` = graphifylabs.ai, `[interview]` = creator interview (sales/marketing context, treat as claims), `[community]` = third-party source, `[unverified claim]` = stated somewhere but not confirmed against a primary source. + +--- + +## 1. Prerequisites + +| Requirement | Notes | +|---|---| +| **Python 3.10+** | Required. Check with `python --version`. `[github][pypi]` | +| **An AI coding assistant** | Claude Code is the primary target; Codex, OpenCode, Cursor, and Gemini CLI are also supported. `[github]` | +| **`uv` or `pipx`** (recommended) | Either gives you isolated tool installs and puts `graphify` on your PATH automatically. `[github]` | +| **Ollama** (optional) | Only needed if you want a local LLM backend for *documents*. See [05-local-models-and-backends.md](05-local-models-and-backends.md). `[github]` (verified facts) | +| **`[google]` extra + Google auth** (optional) | Only for the Google Workspace connector. `[github]` (verified facts) | +| **AWS Bedrock access** (optional) | Only if you want a cloud LLM backend via `--backend bedrock`. `[github]` (verified facts) | + +> **Code ingestion is done locally and needs no LLM.** Code files are parsed with a tree-sitter AST (abstract syntax tree) pass — no file contents leave your machine, no API calls. `[github]` Semantic extraction of *docs, papers, and images* is what calls a model (your assistant's provider, or a local backend). `[github]` Video/audio is transcribed locally with Whisper. `[github]` This split is the single most important thing to understand before your first run (see §6). + +--- + +## 2. Install + +The PyPI package is named **`graphifyy`** (double `y`) — the plain `graphify` name on PyPI is an unrelated package. The CLI command you type is still **`graphify`**. `[github]` + +Install and register in one line. The README leads with `uv`: + +```bash +# Recommended — works on Mac and Linux with no PATH setup needed +uv tool install graphifyy && graphify install +# or with pipx +pipx install graphifyy && graphify install +# or plain pip +pip install graphifyy && graphify install +``` + +`[github]` + +**Why `uv` (or `pipx`) is recommended:** both put the CLI in a managed location that's automatically on your PATH, so you avoid the `graphify: command not found` problem. With plain `pip` you may have to add `~/.local/bin` (Linux) or `~/Library/Python/3.x/bin` (Mac) to your PATH yourself, or run `python -m graphify` instead. `[github]` + +### Optional extras + +Install feature groups with bracket syntax. Confirmed in the README's file-type table: + +```bash +pip install "graphifyy[office]" # .docx / .xlsx ingestion +pip install "graphifyy[video]" # video/audio transcription (faster-whisper + yt-dlp) +pip install "graphifyy[mcp]" # MCP stdio server (graphify.serve) +``` + +`[github]` PDFs and images are supported out of the box (no extra needed). `[github]` + +The Google Workspace connector uses a `[google]` extra (`uv tool install "graphifyy[google]"`, then `gws auth login`, run with `--google-workspace`), verified in the v0.8.30 README and detailed in [04-ingesting-docs-knowledge.md](04-ingesting-docs-knowledge.md). `[github]` Other extra names seen on the PyPI listing (`pdf`, `neo4j`, `anthropic`, `all`, …) should be confirmed against the PyPI page or `graphify --help` before you rely on them. `[pypi]`/`[unverified claim]` + +--- + +## 3. Register with your assistant + +`graphify install` (already chained into the install command above) drops the platform-specific skill manifest into your assistant's config directory so you can invoke `/graphify` from inside the assistant. For Claude Code on Mac/Linux this is all you need. `[github]` + +Target a specific assistant with `--platform` (or a per-platform subcommand). From the README's platform table `[github]`: + +| Platform | Install command | +|---|---| +| Claude Code (Linux/Mac) | `graphify install` | +| Claude Code (Windows) | `graphify install` (auto-detected) or `graphify install --platform windows` | +| Codex | `graphify install --platform codex` | +| OpenCode | `graphify install --platform opencode` | +| Gemini CLI | `graphify install --platform gemini` | +| GitHub Copilot CLI | `graphify install --platform copilot` | +| Cursor | `graphify cursor install` | +| Aider | `graphify install --platform aider` | + +(Full list in the README also covers VS Code Copilot Chat, Trae, Kiro, Hermes, Factory Droid, OpenClaw, and Google Antigravity.) `[github]` + +> Codex calls skills with `$` instead of `/`, so type `$graphify .` there. Codex also needs `multi_agent = true` under `[features]` in `~/.codex/config.toml` for parallel extraction. `[github]` + +### Make the assistant *always* use the graph (recommended) + +Registering the skill lets you call `/graphify` on demand. To make your assistant consult the graph automatically before grepping files, run the always-on installer **after** you've built a graph in a project: + +```bash +graphify claude install # Claude Code: writes a CLAUDE.md section + a PreToolUse hook +``` + +For Claude Code this adds a `CLAUDE.md` note telling Claude to read `graphify-out/GRAPH_REPORT.md` before architecture questions, plus a PreToolUse hook (in `settings.json`) that fires before Glob/Grep and reminds Claude to navigate via the graph. Equivalent per-platform commands exist (`graphify codex install`, `graphify gemini install`, `graphify cursor install`, etc.); uninstall with the matching `... uninstall`. `[github]` + +### Manual install (no package manager) + +The README documents a curl-based fallback that copies the skill into `~/.claude/skills/graphify/SKILL.md` and adds a trigger line to `~/.claude/CLAUDE.md`. Use this only if you can't use `uv`/`pipx`. `[github]` + +--- + +## 4. First run + +From inside your assistant (Claude Code, etc.): + +``` +/graphify . +``` + +Or from a plain shell (on **Windows/PowerShell**, drop the slash — `/` is read as a path separator): + +```bash +graphify . +``` + +This reads the files in the target folder, builds the knowledge graph, and writes everything into a `graphify-out/` directory. `[github]` You can point it at any folder — a codebase, a notes directory, a folder of papers. `[github]` + +> **Three invocation contexts — know which one you're in** `[github]`: +> - **Inside your AI assistant:** `/graphify .` — semantic extraction uses your IDE session's model (no API key needed). +> - **Windows / plain shell:** `graphify .` (no leading slash) — same skill. +> - **Headless / CI:** `graphify extract ./path` (build) and `graphify update ./path` (incremental) — these run standalone and need a backend: an API key (`ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, …) **or** a local `--backend ollama`. Code (AST) is always free; only documents need the backend. See [05-local-models-and-backends.md](05-local-models-and-backends.md). + +Useful first-run variants `[github]`: + +```bash +graphify ./docs # run on a specific folder +graphify . --update # re-extract only changed files, merge into existing graph +graphify . --no-viz # skip the HTML, just produce the report + JSON +graphify . --mode deep # more aggressive INFERRED edge extraction +``` + +> A `--force` flag (or `GRAPHIFY_FORCE=1`) forces a full rebuild and overwrites the graph even when it ends up with fewer nodes — use it after a refactor that deleted files, to clear lingering "ghost" nodes. Verified in the v0.8.30 README. `[github]` See [07-token-economics-and-updates.md](07-token-economics-and-updates.md). + +> Add a `.graphifyignore` file (same syntax as `.gitignore`) at your repo root to exclude folders like `node_modules/`, `dist/`, or generated files from the graph. `[github]` + +--- + +## 5. What you get and where it lands + +Everything is written under **`graphify-out/`** in the directory you ran against. From the README's literal output tree `[github]`: + +``` +graphify-out/ +├── graph.html interactive graph — open in any browser, click nodes, search, filter by community +├── GRAPH_REPORT.md god nodes, surprising connections, suggested questions +├── graph.json persistent graph — query weeks later without re-reading files +└── cache/ SHA256 cache — re-runs only process changed files +``` + +The three headline outputs map to the verified "interactive HTML graph, markdown report, JSON graph file": **`graph.html`**, **`GRAPH_REPORT.md`**, **`graph.json`**. `[github]` + +Optional extra outputs are opt-in via flags, not produced by default: `--obsidian` writes an Obsidian vault, `--wiki` writes `index.md` + per-community articles, `--svg` writes `graph.svg`, `--graphml` writes `graph.graphml`, `--neo4j` writes `cypher.txt`. Video/audio runs also create `graphify-out/transcripts/`. `[github]` + +### Confirming it worked + +1. **Check the directory:** `graphify-out/` exists and contains `graph.html`, `GRAPH_REPORT.md`, and `graph.json`. `[github]` +2. **Open the report:** `GRAPH_REPORT.md` lists the **god nodes** (highest-degree concepts), surprising connections, and 4–5 suggested questions. If you see god nodes, extraction succeeded. `[github]` See [06-querying-and-god-nodes.md](06-querying-and-god-nodes.md). +3. **Watch the token benchmark:** Graphify prints a token benchmark automatically after every run, showing tokens-per-query vs. reading the raw files. `[github]` +4. **Open the graph:** open `graph.html` in a browser to click through nodes and communities. `[github]` +5. **Sanity-check the CLI:** `graphify --help` confirms the binary is on your PATH and lists available commands/flags. `[unverified claim]` + +> On a tiny corpus (a handful of files) the token reduction may be ~1x — that's expected. At that size the value is structural clarity, not compression; reductions scale with corpus size. `[github]` More on this in [07-token-economics-and-updates.md](07-token-economics-and-updates.md). + +--- + +## 6. Avoid blowing your token limit on the first run + +This is the #1 new-user mistake. In the interview, a user described running Graphify cold and burning through their entire daily limit plus ~$25–30 extra on top of a $100/mo Claude plan. `[interview]` + +The cause: pointing Graphify at a big pile of *documents* and letting it call a **cloud model** (your assistant's provider) to extract every chunk. The fix is to understand what actually costs tokens: + +- **Code → local AST, free.** Code parsing uses tree-sitter AST locally with **no model calls** and no file contents leaving your machine. Run it on codebases freely. `[github][interview]` +- **Docs / papers / images → model, costs tokens.** Only these go to a model for semantic extraction. `[github]` To make that free too, point the document backend at **Ollama** (a local small language model). `[interview]` (verified facts: `--backend ollama`) See [05-local-models-and-backends.md](05-local-models-and-backends.md). +- **The first build costs tokens; queries are where you save.** The initial extraction pays the token cost; every later query reads the compact graph instead of raw files, and the SHA256 cache means re-runs only re-process changed files. `[github]` +- **Use `--update`, not full rebuilds.** When adding files later, re-run with `--update` so the cache reuses prior work instead of starting fresh. `[interview][github]` See [07-token-economics-and-updates.md](07-token-economics-and-updates.md). +- **Split large doc sets** and re-ingest in pieces rather than dumping one giant chunk in a single run. `[interview]` + +**Practical first run:** start on a code folder (free), confirm the graph looks right, then add documents with a local Ollama backend before scaling up. + +--- + +## 7. Platform notes + +**macOS / Linux:** `uv tool install graphifyy` or `pipx install graphifyy` both put `graphify` on your PATH with no setup. If you used plain `pip` and get `graphify: command not found`, add `~/.local/bin` (Linux) or `~/Library/Python/3.x/bin` (Mac) to your PATH, or run `python -m graphify`. `[github]` + +**Windows:** Plain-`pip` scripts land in `%APPDATA%\Python\PythonXY\Scripts` — add that to your PATH, or just use `uv`/`pipx`. For Claude Code on Windows, `graphify install` auto-detects the platform (or use `--platform windows`). `[github]` + +**WSL / Ubuntu:** Ubuntu ships `python3`, not `python`. For the MCP server path, install into a project venv to avoid PEP 668 conflicts: `python3 -m venv .venv && .venv/bin/pip install "graphifyy[mcp]"`. `[github]` + +--- + +## 8. Copy-pasteable quickstart + +```bash +# 1. Prereqs: Python 3.10+ and uv (or pipx). Check Python: +python --version + +# 2. Install Graphify + register the skill (package is "graphifyy" with double y; +# command stays "graphify"). Recommended — no PATH setup on Mac/Linux: +uv tool install graphifyy && graphify install +# or: pipx install graphifyy && graphify install +# other assistants: graphify install --platform codex (Cursor: graphify cursor install) + +# 3. (Optional) make the assistant always consult the graph before grepping: +graphify claude install + +# 4. First run — start with a CODE folder (AST parsing is free, no LLM): +graphify . + +# 5. Confirm it worked: +ls graphify-out/ # expect graph.html, GRAPH_REPORT.md, graph.json +# open graphify-out/GRAPH_REPORT.md -> check the god nodes +# open graphify-out/graph.html -> explore the graph + +# 6. For DOCUMENTS, use a local model so you don't burn tokens — see doc 05. +# Then add incrementally: +graphify ./docs --update +``` + +Next: [05-local-models-and-backends.md](05-local-models-and-backends.md) (keep document ingestion free with Ollama) and [07-token-economics-and-updates.md](07-token-economics-and-updates.md) (incremental updates and where the savings come from). Concept refresher: [01-overview-concepts.md](01-overview-concepts.md). + +--- + +## Open questions / unverified + +- **README version skew (resolved).** The repo ships two READMEs: a short `main`-branch one (leads with `pip install`, omits several flags) and the comprehensive **v0.8.30 release** README (leads with `uv tool install graphifyy && graphify install`, documents the full flag set). This doc — and the rest of this guide — anchors on **v0.8.30**, the current release. If a doc page elsewhere disagrees, prefer the v0.8.30 release README, and confirm with `graphify --help` on your installed version. +- **`[google]` Workspace connector + `--backend ollama`/`bedrock` env vars** (`OLLAMA_BASE_URL`, `gws auth login`, `--google-workspace`, etc.) are all in the v0.8.30 README. See [04-ingesting-docs-knowledge.md](04-ingesting-docs-knowledge.md) and [05-local-models-and-backends.md](05-local-models-and-backends.md) for exact syntax. +- **Some extra names** (`pdf`, `neo4j`, `anthropic`, `all`) come from the PyPI listing; `[office]`, `[video]`, `[mcp]` are README-confirmed. Confirm others before relying on them. +- **`graphify --help`** as the post-install sanity check is inferred convention, not explicitly documented. `[unverified claim]` +- **Output directory** is `graphify-out/` relative to the run target per the README's literal tree; whether it can be relocated is not documented here. diff --git a/docs/graphify/03-ingesting-code-ast.md b/docs/graphify/03-ingesting-code-ast.md new file mode 100644 index 0000000..c56cf1a --- /dev/null +++ b/docs/graphify/03-ingesting-code-ast.md @@ -0,0 +1,202 @@ +# Ingesting Code with the AST (Free, No LLM) + +How Graphify turns a codebase into a graph using tree-sitter abstract syntax trees (ASTs) — a deterministic, local, zero-API-cost pass. This is the cheapest thing Graphify does, and the interview's core rule is to lean on it: **use the AST for code, and save the LLM for documents.** + +> Related: [01 Overview & Concepts](./01-overview-concepts.md) · [02 Installation & Setup](./02-installation-setup.md) · [04 Ingesting Docs & Knowledge](./04-ingesting-docs-knowledge.md) · [06 Querying & God Nodes](./06-querying-and-god-nodes.md) · [07 Token Economics & Updates](./07-token-economics-and-updates.md) + +--- + +## The core rule: AST for code, LLM for documents + +The creator states this plainly, more than once: parsing a codebase does **not** call an LLM, so don't pay for one. + +> "The main problem if you are running... an LLM to parse your codebase, that doesn't make sense at all... Abstract syntax trees. It's a free Python library which can connect various parts of a codebase like functions... and create relationships between them in different files even in multiple repository. So it's free of cost." `[interview]` + +Verified against the repo: the first pass is a deterministic tree-sitter walk over every code file with **no LLM, no embeddings, no network** — AST nodes are converted directly into graph nodes and edges. `[github]` + +What this means in practice: + +- Running `graphify .` on a pure code repo costs **nothing** — no API key needed, no token burn, runs entirely on your machine. `[github]` +- You only spend tokens (cloud or local) on **non-code** content: docs, PDFs, transcripts, images. See [04 Ingesting Docs & Knowledge](./04-ingesting-docs-knowledge.md) and [05 Local Models & Backends](./05-local-models-and-backends.md). +- The interview anecdote of "it ran through my whole daily limit" comes from letting an LLM touch the code path. Index code first (free), then decide what documents are worth an LLM call. `[interview]` + +--- + +## How tree-sitter AST extraction works (high level) + +[tree-sitter](https://tree-sitter.github.io/tree-sitter/) is a parser library that turns source files into a concrete syntax tree. Graphify walks that tree to pull out the structural facts of your code. + +> "Tree-sitter parses your code files and extracts classes, functions, imports, call graphs, and inline comments. This runs locally with no LLM involved." `[github]` + +The pipeline, as documented: + +1. **Walk every code file** with tree-sitter (deterministic, local). `[github]` +2. **Extract symbols** — classes, functions, imports, inline comments — and turn each into a graph **node** with an identifier and label. `[github]` +3. **Call-graph pass** — a follow-up pass that links the nodes into **edges**: function `calls`, file `imports`, implementations, and other typed relationships across files. `[github]` +4. **Tag every relationship** with a confidence label so you can tell code-derived facts from inferred ones: + - `EXTRACTED` — found directly in the source (this is what the AST path produces). `[github]` + - `INFERRED` — model inference, with a confidence score (~0.55–0.95). `[github]` + - `AMBIGUOUS` — uncertain, flagged for manual review. `[github]` + + For a pure AST run with no LLM, relationships are `EXTRACTED`. `INFERRED`/`AMBIGUOUS` show up when an LLM enriches the graph (deep mode / documents). + +### What gets linked into the graph + +| Source artifact | Becomes | Linked by | +| --- | --- | --- | +| File | Node | `imports` edges to other files `[github]` | +| Class / function | Node | `calls` edges (call graph), `implements` edges `[github]` | +| Import statement | Edge | connects the importing file/symbol to its target `[github]` | +| Inline comments | Captured with the symbol | provide context for later querying `[github]` | + +The most-connected nodes surface as **god nodes** — the densest hubs in the graph, your fastest way to read an unfamiliar architecture. Query them first. Details in [06 Querying & God Nodes](./06-querying-and-god-nodes.md). `[github]` `[interview]` + +--- + +## Supported languages (33, via tree-sitter) + +The current release (v8) lists **33 languages**. Verified verbatim from the v8 code-extension table: `[github]` + +``` +.py .ts .js .jsx .tsx .mjs .go .rs .java .c .cpp .h .hpp .rb .cs .kt +.scala .php .swift .lua .luau .zig .ps1 .ex .exs .m .mm .jl .vue +.svelte .astro .groovy .gradle .dart .v .sv .svh .sql .f .f90 .f95 +.f03 .f08 .pas .pp .dpr .dpk .lpr .inc .dfm .lfm .lpk .sh .bash .json +.dm .dme .dmi .dmm .dmf .sln .csproj .fsproj .vbproj .razor .cshtml +``` + +By language family, that covers (non-exhaustive, all `[github]`): + +- **Mainstream:** Python, TypeScript/JavaScript (+ JSX/TSX/MJS), Go, Rust, Java, C/C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Dart. +- **Systems / scientific:** Zig, Lua/Luau, Julia, Fortran (`.f` … `.f08`), MATLAB/Objective-C (`.m`/`.mm`), Verilog/SystemVerilog (`.v`/`.sv`/`.svh`). +- **Web frameworks:** Vue, Svelte, Astro, Razor/cshtml. +- **JVM build / scripting:** Groovy, Gradle. +- **Data / schema:** **SQL** schemas, JSON. +- **Shell:** **`.sh`, `.bash`, and PowerShell `.ps1`** — see the note below. +- **Project files:** `.sln`, `.csproj`, `.fsproj`, `.vbproj`. +- **Niche:** Pascal/Delphi (`.pas`/`.dpr`/…), BYOND DreamMaker (`.dm`/`.dme`/…). + +> The repo's own tagline confirms the breadth: it turns "any folder of code, SQL schemas, R scripts, shell scripts, docs, papers, images, or videos into a queryable knowledge graph." `[github]` + +### Shell scripts: now supported by AST (interview was outdated) + +This is a place where the **GitHub repo supersedes the interview**, so read carefully if you watched the video. + +In the interview, the creator said shell scripts were *not* handled by the AST path and prescribed a workaround: + +> "Shell scripts are very flat... rather than going with an A[ST] which isn't capab[le] at the moment for shell scripts, what you can do is just put those as documents and then make the LLM do a semantic extraction of a shell script... That's a temporary fix. I'll get it sorted maybe in coming releases." `[interview]` + +As of the current release (v8), that fix has shipped: `.sh`, `.bash`, and `.ps1` are in the code-extension table and are parsed via tree-sitter like any other language — locally, no API call. `[github]` So the interview's workaround is **no longer necessary for shell scripts**; just run `graphify .` and they'll be extracted for free. + +### Fallback for any unsupported language + +The document-ingestion trick the creator described is still useful — just reframe it for **any file whose language isn't in the 33** (or any code so unusual the AST extraction is thin). Instead of forcing it through the AST path, ingest it as a **document** so an LLM does semantic extraction of its structure: + +- Point Graphify at it as document content (see [04 Ingesting Docs & Knowledge](./04-ingesting-docs-knowledge.md)) and let a local Ollama model or a cloud model pull out nodes. `[interview]` +- This costs tokens (it's an LLM call), so reserve it for the handful of files the AST genuinely can't read. For the 33 supported languages, always prefer the free AST path. `[interview]` + +--- + +## Indexing a repo: `graphify .` + +Run it from the repo root. `[github]` + +```bash +# index the current directory (free, AST-only for code) +graphify . + +# or a specific folder +graphify ./services/api +``` + +This writes three artifacts you and your team can query: `[github]` + +- `graph.html` — interactive visualization. +- `graph.json` — the queryable graph. +- `GRAPH_REPORT.md` — human-readable audit (includes god nodes and confidence tags). + +> Install with `uv tool install graphifyy` (or `pipx install graphifyy`). Full setup, including how to wire it into Claude Code, is in [02 Installation & Setup](./02-installation-setup.md). `[github]` + +After indexing, query the graph — and ask for **god nodes first** before drilling in. That keeps token use minimal on the retrieval side. See [06 Querying & God Nodes](./06-querying-and-god-nodes.md). `[interview]` + +--- + +## Re-indexing after changes: `--update` + +Always use `--update` when re-ingesting an already-indexed repo. It avoids rebuilding from scratch. + +```bash +graphify . --update +``` + +> "I've used hashing strategy [SHA]256 in here, so it will start from where it left... make sure you use the word update as well, `graphify update`, so that it doesn't start fresh from the beginning." `[interview]` + +Verified mechanics: Graphify fingerprints each extracted file with **SHA256 content hashing** and caches under `graphify-out/cache/`. On a re-run with `--update`, unchanged files are skipped entirely; only new/modified files are re-extracted. There are also de-duplication techniques to minimize duplicate entities across files. `[github]` `[interview]` + +More on incremental updates and the token math in [07 Token Economics & Updates](./07-token-economics-and-updates.md). + +--- + +## Auto-rebuild on commit: `graphify hook install` + +To keep the graph fresh without remembering to re-run it, install the git hooks: + +```bash +graphify hook install +``` + +This sets up **post-commit and post-checkout** hooks that rebuild the graph automatically — and because it's the AST path for code, there's no API cost. `[github]` This directly addresses the interview's "my assets become stale over time" concern: the graph stays current as you commit. `[interview]` + +--- + +## Many repos / a whole enterprise in one graph + +The AST path links symbols **across files and across repositories**, so an entire codebase — or a whole company's set of repos — can live in one graph. `[interview]` + +> "It can connect... functions and all of those sections of a code all together and create relationships between them in different files even in multiple repository." `[interview]` + +The verified mechanism is the **`graphify global`** command family, which maintains a cross-project index at `~/.graphify/global.json`: `[github]` + +```bash +# 1) index each repo individually (free, AST) +cd /path/to/repo-a && graphify . +cd /path/to/repo-b && graphify . + +# 2) register each repo's graph into the global cross-project graph +graphify global add graphify-out/graph.json repo-a +graphify global add graphify-out/graph.json repo-b + +# 3) inspect / manage the global graph +graphify global list # shows registered repos with node + edge counts +graphify global remove repo-a # unregister a repo +``` + +This is the "digital twin of your whole enterprise" use case from the interview: a new senior hire can read the architecture in one shot instead of spending days and Slack threads spelunking. `[interview]` See [08 Workflows & Use Cases](./08-workflows-and-use-cases.md). + +--- + +## A concrete first run + +```bash +# from a repo you've never indexed +graphify . # free AST extraction of all 33 supported languages + +# read the architecture: open graph.html, skim GRAPH_REPORT.md, +# then query for the god nodes first (see doc 06) +graphify query "what are the god nodes?" + +# keep it fresh +graphify hook install # auto-rebuild on every commit +# ...or manually after a batch of changes: +graphify . --update +``` + +--- + +## Open questions / unverified + +- **Exact per-language extraction depth.** The 33-language list is verified, but how thoroughly each language's call graph is resolved (e.g., dynamic dispatch in Ruby/Python, macro-heavy Rust) is not documented. `[unverified claim]` +- **`--update` vs. a bare `graphify global` re-add.** Whether updating a member repo automatically propagates into an already-registered global graph, or requires re-running `graphify global add`, isn't spelled out in the docs I checked. `[unverified claim]` +- **`graphify global path` semantics.** A `graphify global path` command appears in the repo listing, but its exact arguments/behavior for cross-repo path queries weren't documented in the sources read. `[github]` (command exists) / `[unverified claim]` (usage) +- **Branch/version skew.** The `main` README I first fetched showed only ~13 languages and an older `pip install graphifyy && graphify install` flow; the **v8** branch shows the full 33 languages, shell support, and `uv tool install`. This doc follows **v8** (newest). If you're on an older install, your supported-language list and command surface may be narrower — check `graphify --help`. `[github]` +- **R scripts.** The repo tagline advertises "R scripts," but `.r`/`.R` does not appear in the v8 code-extension table I verified — R may be handled via the document path rather than AST. `[unverified claim]` diff --git a/docs/graphify/04-ingesting-docs-knowledge.md b/docs/graphify/04-ingesting-docs-knowledge.md new file mode 100644 index 0000000..ec4e01e --- /dev/null +++ b/docs/graphify/04-ingesting-docs-knowledge.md @@ -0,0 +1,199 @@ +# 04 — Ingesting Documents & a Personal Knowledge Base + +How to turn notes, PDFs, spreadsheets, images, audio/video, and cloud docs into a queryable Graphify graph. Unlike code (free, local AST), documents need an LLM or local SLM to extract meaning — so this is the part of Graphify that costs tokens (or GPU time), and where organization and chunking matter most. + +> **Provenance:** Claims are tagged `[github]` (verified against the v8 repo README/docs on 2026-06-03), `[interview]` (from the creator interview — treat as intent/sales claims), `[community](url)`, or `[unverified claim]`. Never assume a flag exists because it sounds plausible — every command below was copied from the verified README unless tagged otherwise. + +Related docs: [code/AST ingest](03-ingesting-code-ast.md) · [local models & backends](05-local-models-and-backends.md) · [querying & god nodes](06-querying-and-god-nodes.md) · [token economics & updates](07-token-economics-and-updates.md) · [workflows](08-workflows-and-use-cases.md). + +--- + +## The one rule that governs cost + +Graphify runs a multi-pass pipeline. The split that matters for your wallet: **code is extracted locally with no API calls (AST via tree-sitter); everything else goes through your AI assistant's model API.** `[github]` + +- **Code files** — processed locally via tree-sitter. Nothing leaves your machine, no tokens spent. `[github]` (see [03-ingesting-code-ast.md](03-ingesting-code-ast.md)) +- **Video / audio** — transcribed locally with faster-whisper. Nothing leaves your machine. `[github]` +- **Docs, PDFs, images** — sent to your AI assistant for semantic extraction. `[github]` + +In the creator's words: *"You have to call the LLM backend only for your documents… [for code] there's no API call included."* `[interview]` So the practical takeaway is: code is free to graph; **documents always need a backend** (a cloud LLM or a local SLM via Ollama). Pick the backend deliberately — that decision and its cost trade-offs live in [05-local-models-and-backends.md](05-local-models-and-backends.md) and [07-token-economics-and-updates.md](07-token-economics-and-updates.md). + +--- + +## Supported non-code formats + +Verbatim from the v8 format table `[github]`: + +| Type | Extensions | Notes | +|------|-----------|-------| +| Docs | `.md .mdx .qmd .html .txt .rst .yaml .yml` | Plain text / markup | +| Office | `.docx .xlsx` | requires `uv tool install "graphifyy[office]"` | +| Google Workspace | `.gdoc .gsheet .gslides` | opt-in; requires `gws` auth + `--google-workspace`; Sheets need `graphifyy[google]` | +| PDFs | `.pdf` | requires `uv tool install "graphifyy[pdf]"` | +| Images | `.png .jpg .webp .gif` | vision-based extraction (screenshots, diagrams) `[unverified claim]` on per-language fidelity | +| Video / Audio | `.mp4 .mov .mp3 .wav` and more | requires `uv tool install "graphifyy[video]"` (faster-whisper + yt-dlp) | +| YouTube / URLs | any video URL | requires `uv tool install "graphifyy[video]"` | + +Optional extras are installed once and add format support; install only what you need: + +```bash +uv tool install "graphifyy[pdf]" # PDF extraction +uv tool install "graphifyy[office]" # .docx and .xlsx +uv tool install "graphifyy[video]" # video/audio transcription (faster-whisper + yt-dlp) +uv tool install "graphifyy[google]" # Google Sheets table rendering +``` + +`uv tool install` installs a single tool, so each line above *replaces* the previous install. To get several extras at once, combine them in one bracket (comma-separated) or grab everything: + +```bash +uv tool install "graphifyy[pdf,office,video,google]" # combine extras in one install +uv tool install "graphifyy[all]" # everything +``` + +> Note the PyPI package is `graphifyy` (double-y) while the command is `graphify`. `[github]` See [02-installation-setup.md](02-installation-setup.md). + +--- + +## Two ways to run: in-IDE skill vs. headless CLI + +This trips people up, so be explicit. Graphify has two invocation forms, and they are **not** interchangeable: `[github]` + +- **In-IDE skill** — `/graphify ...` (slash command). Runs inside your Claude Code / Cursor / Gemini CLI session and uses *whatever model that session runs* for document extraction. This is the path the interview mostly describes. +- **Headless CLI** — `graphify extract ...`. Runs from a terminal and needs you to choose a backend explicitly (an API key, a running Ollama instance, or the `claude` CLI binary). + +Examples: + +```bash +# In-IDE skill (uses your session's model for docs) +/graphify ./docs +/graphify ./docs --update + +# Headless CLI (you pick the backend) +graphify extract ./docs --backend ollama +graphify extract ./docs --backend gemini +``` + +For everything that follows, the slash form and the `graphify extract` form do the same ingestion — they differ only in *where the model comes from*. + +--- + +## Audio & video transcription (Whisper) + +The interview calls it "whisper"; the shipped implementation is **faster-whisper**, run **locally**. `[github]` Audio and video are transcribed on your machine before any text is sent anywhere, so the transcription step itself is private and free of API tokens (the resulting transcript text is then treated like a document and does hit your backend). `[github]` + +One nice detail: the transcription prompt is seeded with your **top god nodes** (the most-connected concepts in your graph so far), which biases Whisper toward your domain vocabulary. `[github]` + +```bash +uv tool install "graphifyy[video]" # one-time: installs faster-whisper + yt-dlp +/graphify ./media # transcribe local .mp4/.mov/.mp3/.wav, then graph +``` + +### YouTube / lecture transcripts + +The interview's headline KB example — *"put that link, get the lecture's transcription, and then you can have the map of the lecture with each section divided into various graphs"* `[interview]` — is shipped. Add a single video by URL: `[github]` + +```bash +/graphify add # transcribe and add a video +/graphify add https://arxiv.org/abs/1706.03762 # also works for papers/tweets +``` + +This downloads via `yt-dlp`, transcribes locally with faster-whisper, and folds the transcript into the graph as document nodes. `[github]` + +--- + +## Google Workspace connector + +Pull native Google Docs, Sheets, and Slides into a graph. Important gotcha called out in the README: Google Drive for desktop `.gdoc`/`.gsheet`/`.gslides` files are **shortcut pointers, not content** — so you must authenticate the `gws` CLI to fetch the real documents. `[github]` + +```bash +uv tool install "graphifyy[google]" # needed for Google Sheets table rendering +gws auth login -s drive # authenticate the gws CLI (opens a browser, approve scopes) +graphify extract ./docs --google-workspace +``` + +Equivalently, set `GRAPHIFY_GOOGLE_WORKSPACE=1` instead of passing the flag. `[github]` Under the hood, Graphify exports the shortcuts into `graphify-out/converted/` as Markdown sidecars, then extracts those. `[github]` The `gws` CLI itself is a separate Google tool ([googleworkspace/cli](https://github.com/googleworkspace/cli)). `[github]` + +> Because these are documents, the same backend rule applies: a Workspace ingest spends tokens (or local SLM time). `[github]` + +--- + +## Roadmap connectors — NOT yet shipped + +The interview previews several connectors. As of the v8 repo (2026-06-03) **none of these are in Graphify** — treat them as roadmap until a release confirms otherwise: `[interview]` + +- **Slack messages** — *"you can connect your Slack messages… as a map"* `[interview]`. Not in the docs. `[github]` (absent) +- **OneNote** ("one node" in the transcript, likely OneNote) — *"even your one node"* `[interview]`. Not in the docs. `[github]` (absent) +- **Meeting transcripts** — *"even your meetings, the meeting transcripts… everything will be in a brain"* `[interview]`. Not in Graphify. Note: the repo mentions **Penpax**, a *separate* always-on product built on top of Graphify that covers "meetings, browser history, emails, files, and code" `[github]` — so meeting capture appears to be a Penpax feature, not core Graphify. + +If you need any of these today, the interview's own workaround applies: export to a supported document format (e.g. a Slack export or a `.txt`/`.md` transcript) and ingest it as a regular doc. `[interview]` + +--- + +## Organizing a mixed personal knowledge base + +A personal KB is usually a pile of notes + PDFs + media + cloud docs. A few practical principles: + +**1. Group by graph, not by one giant folder.** The interview's strongest cost/quality advice: *"you can split your repository or your documents… and reingest them rather than putting the whole chunk of documents in one shot."* `[interview]` And: *"the more the context… there will be a massive chance of hallucination or dilution in the reasoning."* `[interview]` So build several focused graphs (e.g. `research/`, `meeting-notes/`, `personal-wiki/`) rather than one undifferentiated dump. You can later combine graphs: `graphify merge-graphs a.json b.json`. `[github]` + +**2. Keep code and docs in separate runs where you can.** Code is free (AST); docs cost. Splitting them makes it obvious where your tokens go and lets you re-run docs without re-touching code. + +**3. Build incrementally with `--update`.** Don't re-ingest from scratch each time. `[github]` `[interview]` + +```bash +/graphify ./docs --update # re-extract only changed files, merge into existing graph +``` + +Graphify uses SHA-256 hashing + de-duplication so unchanged files are skipped and entities don't collide across documents. `[interview]` `[github]` Details and economics in [07-token-economics-and-updates.md](07-token-economics-and-updates.md). + +**4. Query god nodes first.** Once a KB is graphed, *"always go to the god nodes first and then start retrieving from there"* `[interview]`. A sane number of god nodes means cohesion is good; an explosion of them often signals a corpus that should have been split. See [06-querying-and-god-nodes.md](06-querying-and-god-nodes.md). + +### Chunking & splitting large corpora + +For large documents — and especially when using a **local SLM** with a small context window — tune the chunk size and concurrency rather than throwing the whole corpus at the model: `[github]` + +```bash +graphify extract ./docs --token-budget 30000 # smaller semantic chunks for local/small models +graphify extract ./docs --max-concurrency 2 # fewer parallel LLM calls (useful for local inference) +GRAPHIFY_OLLAMA_NUM_CTX=8192 graphify extract ./docs --backend ollama --token-budget 4000 # tiny chunks for a constrained Ollama context +``` + +`--token-budget` controls semantic chunk size; smaller budgets keep each LLM call inside a modest context window. `--max-concurrency` throttles parallel calls so a local model isn't overwhelmed. `[github]` Pair these with the Ollama env knobs (`GRAPHIFY_OLLAMA_NUM_CTX`, `GRAPHIFY_OLLAMA_KEEP_ALIVE`) covered in [05-local-models-and-backends.md](05-local-models-and-backends.md). + +--- + +## A runnable starter flow for a personal KB + +```bash +# 0) one-time: add the format extras you need (combine in ONE bracket) +uv tool install "graphifyy[pdf,office,video]" + +# 1) graph your markdown notes + PDFs (docs cost tokens — choose a backend) +# in-IDE (uses your session model): +/graphify ./knowledge/notes +# or headless, fully local: +graphify extract ./knowledge/notes --backend ollama --token-budget 8000 + +# 2) add a lecture you want to remember +/graphify add + +# 3) pull in cloud docs +gws auth login -s drive +graphify extract ./knowledge/gdrive --google-workspace + +# 4) keep it fresh as you add files +/graphify ./knowledge/notes --update + +# 5) explore +/graphify query "what connects my notes on retrieval to the Stanford lecture?" +``` + +--- + +## Open questions / unverified + +- **`gws auth login -s drive` scope flag** — verified in the v8 README `[github]`, but the `gws` CLI is third-party; its exact scope syntax may change. Confirm against [googleworkspace/cli](https://github.com/googleworkspace/cli) before relying on it. +- **"71.5x token reduction" and similar multipliers** — sales claims from the README/interview, explicitly described by the creator as corpus-dependent with "no ceiling or floor." `[interview]` Do not treat as a guarantee; see [07-token-economics-and-updates.md](07-token-economics-and-updates.md). +- **Exact full list of "and more" video/audio formats** — README lists `.mp4 .mov .mp3 .wav` plus unspecified others. `[github]` Test your specific format. +- **Whether `/graphify add` accepts non-YouTube video hosts** — README says "any video URL" via yt-dlp `[github]`; coverage depends on yt-dlp support for that host. `[unverified claim]` +- **Slack / OneNote / meeting-transcript connectors** — interview-stated roadmap, confirmed absent from the v8 repo. `[interview]` Meeting capture currently appears to belong to the separate **Penpax** product, not core Graphify. `[github]` Re-check release notes before assuming availability. +- **Image extraction quality for handwriting/dense scans** — README cites vision extraction for "screenshots, diagrams, any language" `[github]`; handwriting fidelity is untested here. diff --git a/docs/graphify/05-local-models-and-backends.md b/docs/graphify/05-local-models-and-backends.md new file mode 100644 index 0000000..5fae0e3 --- /dev/null +++ b/docs/graphify/05-local-models-and-backends.md @@ -0,0 +1,203 @@ +# 05 — Local Models & Backends + +How Graphify decides what (if anything) talks to an LLM, the full menu of backends, and how to run document extraction fully local with Ollama. The short version: **code never needs a model; only documents do** — so backend choice is purely a documents/knowledge-base question. + +See also: [03 — Ingesting code (AST)](03-ingesting-code-ast.md) · [04 — Ingesting docs & knowledge](04-ingesting-docs-knowledge.md) · [07 — Token economics & updates](07-token-economics-and-updates.md). + +--- + +## The one rule that drives everything: code is free, docs cost a model + +Graphify splits its inputs in two: + +- **Code files — processed locally via tree-sitter (AST). No API calls, nothing leaves your machine.** `[github]` (README: *"Code is extracted locally with no API calls (AST via tree-sitter)"* and *"Code files — processed locally via tree-sitter. Nothing leaves your machine."*) This is also the creator's repeated point in the interview: *"The a call is free of cost. There's no API call included for an LLM... You have to call the LLM back end only for your documents."* `[interview]` +- **Docs, PDFs, images — sent to a model for semantic extraction.** `[github]` (README: *"Docs, PDFs, images — sent to your AI assistant for semantic extraction"*). + +So if you only ingest code, **you never pick a backend and never spend a token on extraction.** Backend selection below matters *only* for documents and knowledge bases. + +--- + +## SLM vs LLM — for a non-expert + +The interview leans hard on **SLMs (small language models)** as the local-first future. `[interview]` In plain terms: + +- An **LLM** (large language model — e.g. Claude, GPT, Gemini) is huge. It generally runs in the cloud because it needs a lot of memory / GPU to hold. +- An **SLM** is a smaller model (a few billion parameters) that **fits in ordinary RAM, or in a consumer GPU's VRAM, and runs on your own machine.** Because it runs locally, **your files never go to a cloud provider.** `[interview]` + +The creator's framing: *"large language models do not fit in smaller RAM size. So you need larger RAM or ... GPUs ... to fit them in. So rather than ... LLMs, you can just go for SLMs ... so that their data isn't shared to cloud-based LLMs."* `[interview]` He describes Graphify's direction as a *"local-first AI memory system"* where *"none of your file will be shared with cloud-based LLMs."* `[interview]` + +Reality check: that "as good as a frontier model" claim is the creator's **aspiration**, not a measured fact. `[unverified claim]` For document extraction (chunk → entities/relationships), a competent local instruction-following model is usually *good enough*; for the highest-quality graphs on messy corpora, a cloud model still tends to win. Treat local as the **privacy/cost** choice, cloud as the **max-quality** choice. + +--- + +## The backend menu + +All set per run with `--backend ` on `graphify extract`. `[github]` (README backend list, verbatim: *"gemini, kimi, claude, openai, deepseek, ollama, bedrock, or claude-cli"*.) Each non-local backend reads its credential from an env var: + +| Backend | Flag | Auth | Where data goes | +|---|---|---|---| +| **Ollama (local)** | `--backend ollama` | none for loopback | **Your machine only** | +| **AWS Bedrock** | `--backend bedrock` | IAM via standard AWS credential chain (`AWS_*` / `~/.aws/credentials`) — **no API key** | AWS account | +| **Claude (API)** | `--backend claude` | `ANTHROPIC_API_KEY` | Anthropic | +| **Claude Code CLI** | `--backend claude-cli` | none — uses your Claude subscription | Anthropic | +| **Gemini** | `--backend gemini` | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | Google | +| **OpenAI / compatible** | `--backend openai` | `OPENAI_API_KEY` | OpenAI (or your compatible endpoint) | +| **DeepSeek** | `--backend deepseek` | `DEEPSEEK_API_KEY` | DeepSeek | +| **Kimi (Moonshot)** | `--backend kimi` | `MOONSHOT_API_KEY` | **Moonshot AI servers in China** `[github]` | + +All flag values, env-var names, and auth notes above are quoted from the v8 README env-var table and backend list. `[github]` + +**In-platform vs headless.** When you run Graphify *inside* a coding assistant via the `/graphify` skill, document extraction uses **whatever model your IDE session already runs** (Claude / Gemini / etc.) — no separate key needed. `[github]` (README: *"using whatever model your IDE session runs"*.) Headless `graphify extract` is where you must supply a backend + credential. + +**Auto-detect priority.** If you don't pass `--backend`, headless `graphify extract` picks one based on which key is set, in this order: **Gemini → Kimi → Claude → OpenAI → DeepSeek → Bedrock → Ollama.** `[github]` Pass `--backend` explicitly if you care which one runs (you usually do, for privacy). + +### How to choose + +- **Privacy / offline / zero per-token cost → `--backend ollama`.** Nothing leaves the machine. The interview's recommended default for documents when you want to *"save cost."* `[interview]` +- **Enterprise cloud, no API keys to manage → `--backend bedrock`** (uses your existing IAM). `[github]` `[interview]` +- **Already paying for a coding-assistant subscription → in-platform `/graphify`, or `--backend claude-cli`** to reuse that subscription with no extra key. `[github]` +- **Max extraction quality, simplest setup → a frontier cloud backend** (`claude` / `gemini` / `openai`) with the matching key. + +--- + +## Setting up Ollama (runnable) + +### 1. Install Ollama and pull a model + +[Ollama](https://ollama.com) is a separate program that runs models locally and exposes an HTTP API on `http://localhost:11434`. Install it, then pull an instruction-following model: + +```bash +# Install Ollama: see https://ollama.com/download +# Then pull a model that fits your RAM/VRAM (see "Which model?" below): +ollama pull qwen2.5:7b # example only — pick one that fits your hardware +ollama serve # if not already running as a service +``` + +### 2. Install Graphify with the Ollama extra + +```bash +uv tool install "graphifyy[ollama]" +``` + +> Note the package name is **`graphifyy`** (double-y) and the optional extra is `[ollama]`. `[github]` (README install table.) + +### 3. Run document extraction against Ollama + +```bash +# Local Ollama — no API key needed for loopback: +graphify extract ./docs --backend ollama +``` + +That's it for code, too — but remember, **code uses AST regardless**, so the backend only kicks in for the documents in `./docs`. + +### Ollama environment variables + +All four below are confirmed verbatim in the v8 README env-var table. `[github]` + +| Env var | Purpose | Default | +|---|---|---| +| `OLLAMA_BASE_URL` | Ollama server URL | `http://localhost:11434` | +| `OLLAMA_MODEL` | Model name to use | auto-detect | +| `GRAPHIFY_OLLAMA_NUM_CTX` | Override Ollama KV-cache (context) window size | auto-sized | +| `GRAPHIFY_OLLAMA_KEEP_ALIVE` | Minutes to keep the model loaded in memory; **set `0` to unload after each chunk** | (model stays loaded) | + +```bash +# Point at a remote Ollama box and pin a specific model: +OLLAMA_BASE_URL=http://192.168.1.50:11434 \ +OLLAMA_MODEL=qwen2.5:7b \ +graphify extract ./docs --backend ollama +``` + +### Tuning `GRAPHIFY_OLLAMA_NUM_CTX` and `KEEP_ALIVE` + +These two are the knobs the README's own troubleshooting section reaches for when *"Ollama runs out of VRAM / context window exceeded."* `[github]` + +**`GRAPHIFY_OLLAMA_NUM_CTX`** — the KV-cache window. Auto-sized by default; override it down if you hit VRAM limits, or up if your chunks are large. Both directions appear verbatim in the README: + +```bash +# Shrink the context window to survive a small GPU (from the VRAM troubleshooting section): +GRAPHIFY_OLLAMA_NUM_CTX=8192 graphify extract ./docs --backend ollama --token-budget 4000 + +# Or raise it for big chunks on a big GPU: +GRAPHIFY_OLLAMA_NUM_CTX=32768 graphify extract ./docs --backend ollama +``` + +**`GRAPHIFY_OLLAMA_KEEP_ALIVE=0`** — unload the model between chunks. Frees VRAM on small GPUs at the cost of reload time per chunk: + +```bash +GRAPHIFY_OLLAMA_KEEP_ALIVE=0 graphify extract ./docs --backend ollama # saves VRAM on small GPUs +``` + +**Slow local models timing out?** Raise the HTTP timeout (default 600s) — README confirms both the env var `GRAPHIFY_API_TIMEOUT` and the `--api-timeout` flag: + +```bash +graphify extract ./docs --backend ollama --api-timeout 900 # 15-minute timeout +``` + +> **Known sharp edge:** community bug reports flag context-window saturation across consecutive chunks on the Ollama backend (the model's session not resetting between chunks, exhausting VRAM after a few chunks). If you see degrading or "hollow" responses partway through a large run, lower `GRAPHIFY_OLLAMA_NUM_CTX` and/or set `GRAPHIFY_OLLAMA_KEEP_ALIVE=0`. `[community](https://github.com/safishamsi/graphify/issues/798)` + +### Which Ollama model? + +**There is no official Graphify-recommended/tested model list.** Neither the v8 README nor the site publishes one (verified — see Open questions). So follow the rule the task itself sets and the interview implies: **pick an instruction-following model that fits your RAM/VRAM.** `[interview]` Document extraction is "read this chunk, emit structured entities/relationships," which is an instruction-following + structured-output job, not deep reasoning. + +Rough sizing rule of thumb: a model needs roughly its parameter count in **GB of (V)RAM** at common 4-bit quantization (a 7B model ≈ ~5 GB; a 30B+ model wants 24 GB+ VRAM). Leave headroom for the context window. + +Community signals (not Graphify-verified): + +- A user feature-request reports running **`gemma3:27b`-class models on a 24 GB+ VRAM GPU** with custom `num_ctx`/concurrency settings for high GPU saturation. Treat the specific tag and numbers as one user's setup, not a spec. `[community](https://github.com/safishamsi/graphify/issues/792)` +- General Ollama guidance points to **Qwen2.5 (e.g. `qwen2.5:7b`)** and **Phi-4 (`phi4:14b`)** as strong instruction-following / structured-output models in their size classes. Good *starting points* to test, not Graphify endorsements. `[community](https://ollama.com/library)` + +Start with the largest instruction-following model that comfortably fits your hardware, run a small `extract`, then check the [god nodes](06-querying-and-god-nodes.md) to judge whether the graph quality is acceptable before committing to a big run. + +--- + +## Controlling spend & local load: `--token-budget` and `--max-concurrency` + +These two govern *how* document chunks are sent to whatever backend you chose. Both are confirmed in the v8 README. `[github]` + +- **`--token-budget`** — size of each semantic chunk sent to the model. **Smaller budget = smaller chunks**, which is the recommended setting for local/small models (less context per call, fits small windows). `[github]` (README: *"smaller semantic chunks for local/small models"*.) +- **`--max-concurrency`** — number of parallel LLM calls. **Lower it for local inference** so you don't overwhelm a single GPU/CPU. `[github]` (README: *"fewer parallel LLM calls (useful for local inference)"*.) + +```bash +# Gentle on a single local GPU: small chunks, low concurrency, generous timeout +GRAPHIFY_OLLAMA_NUM_CTX=8192 \ +graphify extract ./docs \ + --backend ollama \ + --token-budget 4000 \ + --max-concurrency 2 \ + --api-timeout 900 +``` + +For **cloud** backends, the same two flags are your cost dials: smaller `--token-budget` and the [`graphify update`](07-token-economics-and-updates.md) incremental flow keep token spend down. The interview's repeated cost advice: extract **code with AST (free)**, only spend model tokens on **documents**, and always **`graphify update`** rather than re-ingesting from scratch. `[interview]` + +--- + +## Quick reference + +```bash +# Fully local document extraction (privacy / zero per-token cost) +graphify extract ./docs --backend ollama + +# Enterprise cloud via existing AWS IAM (no API key) +graphify extract ./docs --backend bedrock + +# Reuse your Claude subscription, no extra key +graphify extract ./docs --backend claude-cli + +# Explicit cloud key +ANTHROPIC_API_KEY=sk-... graphify extract ./docs --backend claude + +# Code only → no backend needed at all (AST is free) +graphify extract ./src +``` + +--- + +## Open questions / unverified + +- **No official Ollama model recommendation exists.** Verified absent from the v8 README env/backend sections and not surfaced on the (403-gated) official site. The model names here are community/general-Ollama signals, tagged as such — not Graphify-tested defaults. +- **`GRAPHIFY_OLLAMA_KEEP_ALIVE` default value** is documented by *behavior* ("minutes to keep loaded; `0` to unload after each chunk") but the README does not state the numeric default. `[github]` +- **`gemma3:27b` exact tag / VRAM numbers** come from a single user issue (#792), not Graphify docs. The original ASR transcript said "Gemma 4 31b," which does not match a shipped tag; treat the community `gemma3:27b`-class figure as illustrative, not authoritative. `[community](https://github.com/safishamsi/graphify/issues/792)` +- **The "SLMs as good as frontier models soon" vision** is the creator's aspiration, not a benchmark. `[unverified claim]` / `[interview]` +- **The 70x/90x token-savings headline numbers** are corpus-dependent sales claims (the creator himself says *"there is no ceiling or floor"*); not used as a basis for any guidance here. `[unverified claim]` / `[interview]` +- Could not confirm any `graphify.yaml` config-file equivalents for these knobs against the raw README; the `graphify.yaml` keys mentioned in issue #792 are a **feature request**, not shipped config. `[community](https://github.com/safishamsi/graphify/issues/792)` diff --git a/docs/graphify/06-querying-and-god-nodes.md b/docs/graphify/06-querying-and-god-nodes.md new file mode 100644 index 0000000..fc52cd6 --- /dev/null +++ b/docs/graphify/06-querying-and-god-nodes.md @@ -0,0 +1,231 @@ +# Querying the Graph & God Nodes + +Querying is the highest-leverage skill in Graphify: a good query makes the graph *do the reading for you* so your assistant spends tokens on an answer, not on re-grepping the corpus. This page is the retrieval playbook — start at god nodes, scalpel down, and trust the graph as your memory. + +Prerequisite: you've built a graph (`graphify-out/graph.json`, `GRAPH_REPORT.md`, `graph.html`). See [03-ingesting-code-ast.md](03-ingesting-code-ast.md) and [04-ingesting-docs-knowledge.md](04-ingesting-docs-knowledge.md). The cost story behind "ask the graph, not the corpus" lives in [07-token-economics-and-updates.md](07-token-economics-and-updates.md). + +--- + +## The core principle: prompt the graph, don't make the LLM read the corpus + +The single most important habit, in the creator's words: + +> "When you are prompting the graph, don't ask the LLM to go through the graph — rather ask the LLM to extract from the graph. So the graph is the memory, the graph is the context." `[interview]` + +The graph **is** the context/memory. You want the assistant to *extract from* it (pull the specific nodes/edges that answer the question), not *traverse* the whole thing (which just re-spends the tokens you built the graph to save) `[interview]`. + +This is backed by how the tool installs itself. The persistent install config tells your assistant to: + +> "consult the knowledge graph for codebase questions — preferring scoped queries like `graphify query ""` over reading the full report or grepping raw files." `[github]` + +On Claude Code and Gemini CLI a hook even fires *before* search-style tool calls (and before reading source files one-by-one) to nudge the assistant onto the graph path `[github]`. So the discipline is partly automated — but you still drive it with good queries. + +--- + +## Step 1 — Always ask for the god nodes first + +**God nodes** are the most-connected concepts — the load-bearing spine of the project. + +> "God nodes — the most-connected concepts in your project. Everything flows through these." `[github]` + +The retrieval playbook starts here every time: + +> "First of all you prompt to give you the god nodes from the whole corpus first of all ... from god nodes you can easily see where you have to prompt and write to minimize as much tokens as possible." `[interview]` + +Get the high-level architecture in one shot, *then* "scalpel" down into the specific nodes you actually need `[interview]`. That ordering — map first, drill second — is where the token savings come from. + +### How to actually surface god nodes (important) + +There is **no** dedicated `graphify god-nodes` command or `--god-nodes` flag. God nodes are surfaced in two honest ways: + +1. **Read the top of `GRAPH_REPORT.md`.** God nodes are the first thing in the report `[github]`: + > "What's in the report: **God nodes** — the most-connected concepts ... Everything flows through these." `[github]` +2. **Ask your assistant** for the high-level architecture; with the graph installed it reads the graph rather than the files `[github]`. + +Do *not* expect `graphify query "what are the god nodes?"` to return the structural ranking — `query` is *semantic search* over content, while the god-node ranking is a structural (degree-based) result that lives in the report `[github]`. You can ask a semantic question to get oriented, but the authoritative hub list is the report. + +To tune that ranking, see `--exclude-hubs` under [clusters](#step-4--community--cluster-detection) below. + +--- + +## Step 2 — Scalpel down: query / path / explain + +Three verified commands cover the drill-down. (Inside an IDE skill they take a `/` prefix, e.g. `/graphify query`; from a plain terminal drop the slash, e.g. `graphify query`. Same command, two entry points `[github]`. On Windows PowerShell, always use the no-slash form `[github]`.) + +| Command | What it does | Use it to | +|---|---|---| +| `graphify query ""` | Semantic search over the graph `[github]` | Find the nodes relevant to a question | +| `graphify path "Node1" "Node2"` | Find connections between two nodes `[github]` | Trace how two things relate | +| `graphify explain "Node"` | Single-node deep-dive `[github]` | Scalpel into one specific node | + +```bash +# semantic search — "extract from the graph" +graphify query "what connects auth to the database?" # [github] +graphify query "show the auth flow" # [github] + +# point at a specific graph file if not in the default location +graphify query "what connects DigestAuth to Response?" --graph graphify-out/graph.json # [github] + +# bound the search to keep the answer (and tokens) tight +graphify query "..." --dfs --budget 1500 # [github] + +# connection between two named nodes +graphify path "UserService" "DatabasePool" # [github] +graphify path "DigestAuth" "Response" # [github] + +# deep-dive a single node — the literal "scalpel" +graphify explain "RateLimiter" # [github] +``` + +The `--dfs --budget` flags are the direct, runnable expression of "minimize tokens": you cap the traversal/budget so the assistant extracts a bounded slice instead of wandering the whole graph `[github]`. + +### Architecture / call-flow diagram + +For a visual map of how the system fits together: + +```bash +graphify export callflow-html # Mermaid architecture/call-flow HTML [github] +graphify export callflow-html --max-sections 8 # cap the number of generated sections [github] +graphify export callflow-html --output docs/arch.html +graphify export callflow-html ./some-repo/graphify-out +``` + +If you installed the git hook, this auto-regenerates on every commit `[github]`. This pairs well with the god-node read: the report tells you *which* nodes matter, the call-flow HTML shows you *how* they connect. + +--- + +## Step 3 — Read the confidence tags + +Every **inferred** relationship is labeled so you know how much to trust it: + +> "Confidence tags — every inferred relationship is marked `EXTRACTED`, `INFERRED`, or `AMBIGUOUS`. You always know what was found vs guessed." `[github]` + +| Tag | Meaning `[github]` (overview doc) | How much to trust | +|---|---|---| +| `EXTRACTED` | "directly found in source" | High — deterministic; for code this is the AST `[github]` | +| `INFERRED` | "logically deduced" | Medium — a model reasoned it out | +| `AMBIGUOUS` | "uncertain connections" | Low — verify before acting | + +Rule of thumb: code edges are `EXTRACTED` from the tree-sitter AST with no model involved `[github]`, so they're solid; `INFERRED`/`AMBIGUOUS` edges came from a language model reading prose `[github]` — weight them down and confirm before you act. (Confidence-tag concept also covered in [01-overview-concepts.md](01-overview-concepts.md).) + +--- + +## Step 4 — Community / cluster detection + +Graphify groups related entities into **communities**, and you can rerun clustering at adjustable granularity *without* re-extracting (so it's free — no API calls): + +```bash +graphify cluster-only ./my-project # rerun clustering on existing graph [github] +graphify cluster-only ./my-project --resolution 1.5 # more, smaller communities [github] +graphify cluster-only ./my-project --exclude-hubs 99 # exclude p99-degree nodes from partitioning [github] +``` + +The same controls exist as flags on a build run: + +```bash +/graphify . --cluster-only # rerun clustering, no re-extract [github] +/graphify . --cluster-only --resolution 1.5 # more granular communities [github] +/graphify . --cluster-only --exclude-hubs 99 # suppress utility super-hubs from god-node rankings [github] +``` + +- **`--resolution`** raises granularity: a higher value (e.g. `1.5`) yields *more, smaller* communities; lower values yield fewer, larger ones `[github]`. Sweep it to find the topic-cluster scale that matches how you think about the project. +- **`--exclude-hubs 99`** drops the very highest-degree utility nodes (e.g. a logger imported everywhere) from the partitioning / god-node ranking so they don't swamp the real structure `[github]`. + +**Cross-community links** — relationships that bridge otherwise-separate clusters — are the thing the creator says plain visualizers (e.g. Obsidian) can't surface `[interview]`. There is **no** dedicated flag for them; they appear in the report as **"surprising connections"**: + +> "Surprising connections — links between things that live in different files or modules. Ranked by how unexpected they are." `[github]` + +So: clusters come from `cluster-only`/`--resolution`; the bridges between them are the ranked "surprising connections" in `GRAPH_REPORT.md`. + +--- + +## Step 5 — The god-node diagnostic heuristic + +A rough health signal from the creator: + +> "If you have large amount of god nodes that means that something has gone wrong with the cohesion or maybe with your codebase ... if you have a decent number of god nodes ... things have worked fine." `[interview]` + +Treat this as an `[interview]` heuristic, not a measured threshold — there's no defined "too many." `[unverified claim]` But it's testable: run `--exclude-hubs 99` to strip out the utility super-hubs and see whether a sane architecture remains underneath `[github]`. If a huge, sprawling god-node set survives even after excluding the obvious utility hubs, that's a soft signal of poor cohesion worth a closer look. (`--exclude-hubs` adjusts the *ranking*; it does not *fix* cohesion.) + +--- + +## Putting it together: inspecting a fresh graph + +A concrete sequence for a graph you've never seen (e.g. a new hire on an unfamiliar codebase — the interview's headline scenario `[interview]`): + +```bash +# 1. Build the graph (AST for code = free, no API calls) [github][interview] +/graphify . + +# 2. Read the high-level map FIRST: god nodes + surprising +# connections are at the top of the report [github][interview] +# -> open graphify-out/GRAPH_REPORT.md + +# 3. See how the spine connects, visually +graphify export callflow-html # [github] + +# 4. Sanity-check cohesion: strip utility super-hubs, re-look +graphify cluster-only . --exclude-hubs 99 # [github] +# too many god nodes left? possible cohesion problem [interview / unverified] + +# 5. Scalpel into specifics — extract from the graph, bounded +graphify query "what connects auth to the database?" --dfs --budget 1500 # [github] +graphify path "UserService" "DatabasePool" # [github] +graphify explain "RateLimiter" # [github] + +# 6. Tune cluster granularity if topics feel too coarse/fine +graphify cluster-only . --resolution 1.5 # [github] +``` + +Throughout: read the **confidence tag** on any edge before you act on it — `EXTRACTED` is trustworthy, `INFERRED`/`AMBIGUOUS` needs a second look `[github]`. + +### Example queries to copy + +```bash +graphify query "what connects attention to the optimizer?" # [github] +graphify query "show the auth flow" # [github] +graphify path "DigestAuth" "Response" # [github] +graphify explain "SwinTransformer" # [github] +``` + +--- + +## Repeated / programmatic access (MCP) + +For an assistant that hits the graph many times in a session, expose it as an MCP server instead of one-off CLI calls: + +```bash +python -m graphify.serve graphify-out/graph.json # [github] +``` + +This gives structured tools: `query_graph`, `get_node`, `get_neighbors`, `shortest_path`, `list_prs`, `get_pr_impact`, `triage_prs` `[github]`. Note `get_neighbors` / `shortest_path` are the programmatic equivalents of `explain` / `path`. (PR-impact tooling — `graphify prs` — is covered in [08-workflows-and-use-cases.md](08-workflows-and-use-cases.md).) + +--- + +## Quick reference + +| Goal | Do this | +|---|---| +| See the architecture spine | Read god nodes at top of `GRAPH_REPORT.md` `[github]` | +| Visual call-flow | `graphify export callflow-html` `[github]` | +| Find relevant nodes (semantic) | `graphify query "..."` (add `--dfs --budget N`) `[github]` | +| Connect two named nodes | `graphify path "A" "B"` `[github]` | +| Deep-dive one node | `graphify explain "Node"` `[github]` | +| Re-cluster (free) | `graphify cluster-only . --resolution 1.5` `[github]` | +| De-noise god-node ranking | `--exclude-hubs 99` `[github]` | +| Bridges between clusters | "surprising connections" in the report `[github]` | +| Judge trust of an edge | Read its `EXTRACTED` / `INFERRED` / `AMBIGUOUS` tag `[github]` | + +Index: [00-README.md](00-README.md) · Next: [07-token-economics-and-updates.md](07-token-economics-and-updates.md) · Workflows: [08-workflows-and-use-cases.md](08-workflows-and-use-cases.md) + +--- + +## Open questions / unverified + +- **No `god-nodes` command exists.** God nodes are surfaced via `GRAPH_REPORT.md` and the assistant, not a dedicated CLI verb. `graphify query` is *semantic search*, not the structural hub ranking — don't conflate them. `[github]` +- **"Too many god nodes = poor cohesion"** is an `[interview]` heuristic with no defined threshold. `[unverified claim]` `--exclude-hubs` lets you *test* it but does not fix cohesion. +- **Cross-community links have no flag.** They map to the report's ranked "surprising connections" `[github]`; the interview's framing that Obsidian "can't do cross-community interaction" `[interview]` is the creator's claim, not independently verified. +- **`--resolution` direction** (higher = more, smaller communities) is from the README's inline comments `[github]`; exact algorithm/parameter semantics aren't documented in the README. +- **`--dfs --budget`** appears in the README command reference `[github]` but the exact budget units (tokens? nodes? hops?) and the `--budget` default are not spelled out there. `[unverified claim]` +- **graphifylabs.ai** returns HTTP 403 to plain fetch, so any query syntax documented only on the official site is not directly verified here. +- **Token-savings figures** ("70x"/"90x"/"20x") are sales claims handled in [07-token-economics-and-updates.md](07-token-economics-and-updates.md), not retrieval facts. `[unverified claim]` diff --git a/docs/graphify/07-token-economics-and-updates.md b/docs/graphify/07-token-economics-and-updates.md new file mode 100644 index 0000000..f5f4b4c --- /dev/null +++ b/docs/graphify/07-token-economics-and-updates.md @@ -0,0 +1,173 @@ +# 07 — Token Economics & Keeping the Graph Fresh + +Where Graphify's token savings actually come from, how honest the headline numbers are, the practical levers you control, and how to keep the graph current with incremental updates instead of rebuilding from scratch. + +> **Provenance:** Claims are tagged `[github]` (verified on 2026-06-03 by reading the raw `skill.md`, `__main__.py`, and `README.md` at the release line this guide anchors on — the `v0.8.x` line, which the brief refers to as "v8"; the disputed flags below were also checked against the `v1.0.0` tag and are absent there too), `[interview]` (creator interview — treat as intent/sales claims), `[community](url)`, or `[unverified claim]`. Several flags people repeat online do **not** exist in the shipped CLI; those are flagged explicitly below. Never assume a flag exists because it sounds plausible — check `--help` or `skill.md`. + +Related docs: [overview](01-overview-concepts.md) · [code/AST ingest](03-ingesting-code-ast.md) · [docs ingest](04-ingesting-docs-knowledge.md) · [local models & backends](05-local-models-and-backends.md) · [querying & god nodes](06-querying-and-god-nodes.md) · [workflows](08-workflows-and-use-cases.md) · [best practices](09-best-practices-checklist.md). + +--- + +## 1. Where the savings actually come from + +Graphify does not "compress" your tokens. The savings come from three mechanics. Understanding them tells you exactly when savings will be large and when they'll be near zero. + +### a) Code extraction is free (local AST) +Code is parsed locally with tree-sitter into an abstract syntax tree. No API calls, no tokens, no cost — just CPU. `[github]` In the creator's words: *"If you are calling an LLM to parse your codebase, that doesn't make sense at all… the AST call is free of cost. There's no API call included."* `[interview]` + +So for a pure-code corpus, **building** the graph is effectively free. Only **documents, papers, and images** go through a model backend (cloud LLM or a local SLM). `[github]` That single split — free code vs. paid docs — is the biggest cost lever you have. (See [04-ingesting-docs-knowledge.md](04-ingesting-docs-knowledge.md).) + +### b) Querying the graph instead of dumping the corpus +The real recurring savings are at **query time**. Instead of letting your assistant read dozens of raw files to orient itself, you query the pre-built graph and pull back only the relevant subgraph. `[github]` The skeptical-but-fair review puts it well: the savings come *"from precision — not from compression — allowing you to pay for relevant tokens, not orientation tokens."* [community](https://www.roborhythms.com/graphify-review/) + +The creator's rule: *"Don't ask the LLM to go through the graph; ask the LLM to extract from the graph. The graph is the memory, the graph is the context."* `[interview]` + +### c) God-nodes-first retrieval +Query the **god nodes** (the highest-connectivity hub nodes / `GRAPH_REPORT.md`) first to get the architecture in one shot, then "scalpel" down into the specific subgraph you need. `[interview]` This avoids the expensive pattern of repeatedly reading files to reconstruct structure the graph already encodes. See [06-querying-and-god-nodes.md](06-querying-and-god-nodes.md). + +--- + +## 2. How honest are the savings numbers? + +**Treat every multiplier as corpus-dependent, not a guarantee.** + +- The README/benchmark headline is **71.5x fewer tokens per query** — but that is from **one specific run**: a mixed corpus of Karpathy repos + 5 papers + 4 images. `[github]` The benchmark is printed automatically after a run via `graphify benchmark`. `[github]` +- The creator is explicit that this is not a floor or a ceiling: *"There is no ceiling or floor in token savings here… 71.5 in my readme is for the repository I tried on. I've seen people getting 90x… and people getting 20x. It's totally corpus dependent."* `[interview]` +- He also acknowledges the backlash directly: *"I have a lot of hate in my comments… 'Oh, 70 times, are you out of your mind?'"* `[interview]` + +**Independent / skeptical takes (read these before quoting a number):** +- An independent review reproduced the mechanism but found the realistic range is roughly **6.8x to 49x**, with the 71x figure being *"the upper bound on a curve… the tail of the distribution, not the middle."* It reports near-**1x–3x savings under ~100 files** and large multipliers only on very large repos. [community](https://www.roborhythms.com/graphify-review/) +- Community criticism also targets non-technical claims — GitHub star-count growth tactics and missing credit for early PR contributors — separate from whether the tool works. [community](https://www.mindstudio.ai/blog/graphify-claude-code-knowledge-graph-large-codebase-70x) + +**Bottom line:** savings scale with corpus size and how disciplined your querying is. Small corpora may save little or nothing (graph-building overhead isn't amortized). Don't promise a multiplier to anyone — measure your own with `graphify benchmark`. `[github]` + +> **The download/star numbers** ("500K+ PyPI downloads", "43K stars") are creator sales claims from the interview. `[interview]` Third-party write-ups cite different figures (e.g. ~55K stars / ~450K downloads). [community](https://www.mindstudio.ai/blog/graphify-claude-code-knowledge-graph-large-codebase-70x) Treat all of these as **unverified and time-sensitive.** `[unverified claim]` + +--- + +## 3. Practical cost levers + +### Lever 1 — Use a local backend (Ollama) for documents +Code is free regardless. The cost is documents. Route document extraction through a **local small language model via Ollama** instead of a paid cloud model. `[interview]` The creator's own workflow: *"local LLM for the extraction… free of cost as well rather than going for a cloud-based LLM."* `[interview]` Backends are installed as optional extras (e.g. `uv tool install "graphifyy[anthropic]"` for the cloud path). `[github]` + +> Note: the package on PyPI is **`graphifyy`** (double *y*); the CLI command is **`graphify`**. `[github]` Exact Ollama/SLM setup steps live in [05-local-models-and-backends.md](05-local-models-and-backends.md). The *intent* (Ollama for docs to cut cost) is well-supported; treat specific Ollama flag syntax as `[unverified claim]` until confirmed against your installed `--help`. + +### Lever 2 — Split large corpora and re-ingest in pieces +Don't dump one giant corpus in a single shot. *"You can split your repository or your documents and then reingest them… rather than putting the whole chunk in one shot."* `[interview]` More context per pass also raises hallucination/dilution risk, so smaller, merged passes are both cheaper and more reliable. `[interview]` Each re-ingest should use `--update` (Section 4) so pieces merge instead of rebuilding. + +### Lever 3 — Cap query answer size with `--budget` +You can cap how many tokens a **query answer** returns: + +```bash +/graphify query "how does auth talk to the database?" --budget 1500 # cap answer at ~1500 tokens +``` + +Default budget is ~2000 tokens; results are ranked by relevance and truncated at the budget. `[github]` + +> **`--budget` vs `--token-budget` — two different flags for two different stages** (both verified in the v0.8.30 README): `--budget N` caps **query answer** size (retrieval), while **`--token-budget N`** controls the **semantic chunk size sent to the model during extraction** (smaller = better for local/small models). `[github]` Don't confuse them — `--budget` is for `query`, `--token-budget` is for `extract`. See [05-local-models-and-backends.md](05-local-models-and-backends.md) for `--token-budget` tuning. + +### Lever 4 — Tune extraction cost with `--token-budget` and `--max-concurrency` +For the **extraction** stage (where document tokens are actually spent), v0.8.30 exposes two real flags: `[github]` + +```bash +graphify extract ./docs --token-budget 30000 # smaller semantic chunks for local/small models +graphify extract ./docs --max-concurrency 2 # fewer parallel LLM calls (useful for local inference) +graphify extract ./docs --api-timeout 900 # longer HTTP timeout for slow local models (default 600s) +``` + +- **`--token-budget N`** — size of each semantic chunk sent to the model. Smaller chunks fit small/local model context windows and reduce tokens per call. `[github]` +- **`--max-concurrency N`** — number of parallel LLM calls; lower it for local inference so you don't overwhelm a single GPU/CPU. `[github]` +- **`--api-timeout` / `GRAPHIFY_API_TIMEOUT`** — HTTP timeout in seconds (default 600). `[github]` + +Under the hood the skill also parallelizes automatically (semantic-extraction subagents over chunks, AST in parallel), so these flags tune — rather than introduce — concurrency. `[github]` Exact Ollama setup and a worked example live in [05-local-models-and-backends.md](05-local-models-and-backends.md). + +--- + +## 4. Incremental updates — always `--update` when adding data + +**The single most important habit.** When you add new files, run `--update` so Graphify re-extracts only what changed and merges into the existing graph, instead of rebuilding from scratch: + +```bash +/graphify ./raw --update # re-extract only new/changed files, merge into existing graph +``` + +The creator hammered this twice: *"When you are ingesting more data, make sure you use the word update — `graphify update` — so it doesn't start fresh from the beginning."* and *"Always make sure you put `graphify update` when you are ingesting new files or codebases or documents, so it doesn't have to go through the whole code once more."* `[interview]` + +**How `--update` knows what changed:** +- **SHA-256 content hashing** of each file. Unchanged files (same hash) are skipped; only changed/new files are re-processed. The cache lives in `graphify-out/cache/`. `[github]` *"I've used hashing strategy SHA-256 in here so it will start from where it left."* `[interview]` +- **Deduplication** of entities so the same node isn't created twice across documents/passes. `[github]` *"I've also got some deduplication techniques so there will be very few collisions of the entities."* `[interview]` + +This is what makes Lever 2 (split + re-ingest) safe: each piece merges cleanly via hash + dedup rather than producing a duplicated or reset graph. + +### "Overwrite" / `--force` semantics — read this carefully +A re-run of the full pipeline (without `--update`) rebuilds the graph rather than merging incrementally. `[github]` + +> **`--force`:** The `--force` flag **does exist** in v0.8.30 (equivalently set `GRAPHIFY_FORCE=1`). It overwrites `graph.json` **even when the rebuild produces fewer nodes**, which is exactly what you want after a refactor that deleted files — otherwise the old "ghost" nodes linger. `[github]` +> +> ```bash +> graphify extract . --force # rebuild, overwrite even if fewer nodes (clears ghost nodes after deletions) +> graphify update ./src --force # same, while still merging changed files +> ``` +> +> Mental model: **`--update` = merge changed files; plain re-run = rebuild; `--force` = rebuild and overwrite even if the graph shrinks.** `[github]` + +--- + +## 5. Auto-rebuild: git hooks and `--watch` + +To avoid forgetting to update, automate it. + +### Git commit hook (recommended for code) +```bash +graphify hook install # post-commit hook: re-runs AST on changed files, rebuilds graph after every commit +graphify hook status # check if installed +graphify hook uninstall # remove it +``` +After each commit the hook detects changed **code** files (via `git diff HEAD~1`), re-runs AST extraction on just those, and rebuilds `graph.json` + `GRAPH_REPORT.md`. `[github]` + +> **Important limitation:** the hook handles **code only**. Doc/image changes are *ignored* by the hook — you must run `/graphify ./raw --update` manually after editing docs, because those need the (paid) LLM semantic re-pass. `[github]` + +### Watch mode (for active/agentic sessions) +```bash +/graphify --watch # watch folder, auto-rebuild on code changes (no LLM) +``` +Code saves trigger an instant AST-only rebuild (free, debounced ~3s). Doc/image changes write a `graphify-out/needs_update` flag and notify you to run `--update`. `[github]` Useful when parallel agents are writing code in waves. `[github]` + +--- + +## 6. The staleness problem (and how the above mitigates it) + +The interview's most candid admission is the operator's real pain point: assets go stale and re-grooming them is a chore. The interviewer: *"My assets become stale over time, so the process of having to remember to groom your data… becomes a bit of a constraint."* `[interview]` The creator's framing is a *"digital twin / enterprise brain that gets smarter with time"* via incremental updates `[interview]` — but that only holds if the graph is actually kept current. + +**How to keep it from going stale (all verified):** +- **Code:** install the commit hook (`graphify hook install`) or run `--watch` during active work — code rebuilds are free and automatic. `[github]` +- **Docs/knowledge:** the hook and watch mode will **not** auto-update these (they cost tokens). Build a habit (or a scheduled job) of running `/graphify ./raw --update` after adding/editing documents. `[github]` +- **Merge, don't reset:** always `--update` so SHA-256 + dedup re-process only what changed and merge it in. `[github]` + +A realistic personal cadence: hook on for every code repo; a periodic `--update` on your docs/notes folder (manually or via cron) so the knowledge base never drifts far from reality. + +--- + +## Quick reference (verified against v0.8.30) + +| Goal | Command | Cost | +|------|---------|------| +| First build of a corpus | `/graphify ` | code free; docs/images cost backend tokens | +| Add/changed data later | `/graphify --update` | only changed files re-processed | +| Richer inference | `/graphify --mode deep` | higher (more LLM passes) | +| Auto-rebuild on commit (code) | `graphify hook install` | free (AST only) | +| Live auto-rebuild (code) | `/graphify --watch` | free (AST only) | +| Query, capped answer | `/graphify query "..." --budget 1500` | small (subgraph only) | +| Smaller chunks for local models | `graphify extract --token-budget 30000` | lowers tokens/call | +| Fewer parallel model calls | `graphify extract --max-concurrency 2` | eases local GPU/CPU load | +| Rebuild, overwrite even if smaller | `graphify extract --force` | clears ghost nodes after deletions | +| Measure your own savings | `graphify benchmark` | free | + +--- + +## Open questions / unverified + +- **Flag set is version-dependent.** All of `--budget`, `--token-budget`, `--max-concurrency`, `--api-timeout`, and `--force` are documented in the **v0.8.30** release README (verified by grepping the raw file). `[github]` The shorter `main`-branch README omits them, so if you're on a different build, confirm with `graphify --help`. +- **Ollama backend specifics** — the *intent* (local SLM for docs to save cost) is well-supported `[interview]`, and backends install as extras `[github]`, but exact Ollama setup/flags were not confirmed from the raw repo here. See [05-local-models-and-backends.md](05-local-models-and-backends.md) and confirm with `--help`. `[unverified claim]` +- **Savings multipliers** — 71.5x is one Karpathy-corpus benchmark; independent testing suggests ~6.8x–49x realistically, ~1x–3x under ~100 files. Always measure your own. [community](https://www.roborhythms.com/graphify-review/) +- **Download/star counts** — creator figures (500K downloads, 43K stars) differ from third-party figures; all are time-sensitive. `[unverified claim]` diff --git a/docs/graphify/08-workflows-and-use-cases.md b/docs/graphify/08-workflows-and-use-cases.md new file mode 100644 index 0000000..ef1f7ed --- /dev/null +++ b/docs/graphify/08-workflows-and-use-cases.md @@ -0,0 +1,221 @@ +# Workflows & Use Cases + +End-to-end playbooks for running Graphify as a one-person operation across code, documents, and a personal knowledge base. Every command below is verbatim from the v8 README; concepts are covered in the sibling docs and cross-linked rather than re-explained. + +> **Provenance:** commands are tagged `[github]` (verified from the [v8 README](https://raw.githubusercontent.com/safishamsi/graphify/v8/README.md)). Claims from the creator interview are tagged `[interview]` and headline savings numbers are **sales claims**, not benchmarks. See [00-README](00-README.md) for the tagging scheme. + +> **Skill vs. CLI prefix:** commands written `/graphify ...` run through the IDE skill (your assistant's model provides the LLM calls for documents — no separate API key). Commands written `graphify ...` are the plain CLI. `graphify extract ...` is the headless form used in CI or when you want to pin a backend explicitly. `[github]` + +--- + +## Playbook 1 — Onboard fast to an unfamiliar codebase + +For a new hire, contractor, or your own first hour in a repo you inherited. The interview frames this as the flagship use case: replace days of code-spelunking and Slack pings with one map. `[interview]` + +1. Map the whole repo. Code is parsed locally via AST — no API calls, no token cost. `[github]` + ```bash + /graphify . + ``` + This writes `graphify-out/graph.html`, `graphify-out/GRAPH_REPORT.md`, and `graphify-out/graph.json`. `[github]` +2. Read the report first, not the source. Open `graphify-out/GRAPH_REPORT.md` for architectural highlights. `[github]` +3. **God nodes first.** Ask the graph for its most-connected concepts before reading any file — these are the architectural chokepoints "everything flows through." `[github]` See [06-querying-and-god-nodes](06-querying-and-god-nodes.md) for the god-node querying pattern. + ```bash + /graphify query "what are the god nodes / most connected components?" + ``` + Heuristic from the creator: a *huge* pile of god nodes signals weak cohesion or a structural mess; a *modest* set means the architecture is sane. `[interview]` +4. Trace the architecture from those hubs outward. + ```bash + /graphify explain "AuthService" + /graphify query "what connects auth to the database?" + ``` +5. Generate a readable architecture page with Mermaid call-flow diagrams to skim the system visually. + ```bash + graphify export callflow-html + ``` + `[github]` + +**ROI framing (sales claim):** the creator pitches this as replacing a $150/hr engineer's multi-day ramp-up with a few free minutes. Treat the dollar figure as illustrative. `[interview]` + +--- + +## Playbook 2 — Fix a bug / ticket by tracing dependencies + +You have a ticket ("users hitting an error on the backend") and need the blast radius before you touch code. + +1. Make sure the graph reflects current `HEAD` (see [Playbook 4](#playbook-4--build-a-persistent-digital-twin--second-brain) for keeping it fresh): + ```bash + /graphify --update + ``` + `[github]` +2. Locate the suspect component via god nodes / a targeted query, then expand its neighborhood: + ```bash + /graphify explain "RateLimiter" + ``` + `[github]` +3. Trace the dependency chain between the failing area and its likely root using shortest path: + ```bash + /graphify path "UserService" "DatabasePool" + ``` + This returns the shortest connection between two entities — the chain of files/functions the bug can propagate through. `[github]` +4. Confirm the blast radius before editing: + ```bash + /graphify query "what depends on DatabasePool?" + ``` +5. Query the graph, don't dump the corpus. Ask the assistant to **extract from the graph** rather than read every file — the graph is your context. `[interview]` Token mechanics in [07-token-economics-and-updates](07-token-economics-and-updates.md). + +--- + +## Playbook 3 — Audit AI-generated "slop" / junk code + +The creator's pitch for non-experts shipping AI-written code fast: map it, then let the graph surface what's wrong. `[interview]` + +1. Map the suspect tree: + ```bash + /graphify . + ``` +2. Look at god-node count as a smell test. An unusually large or sprawling set of god nodes points at poor cohesion — a hallmark of slop. `[interview]` +3. Hunt for orphans and dead ends — nodes with no meaningful connections often mean dead or duplicated code: + ```bash + /graphify query "which components are disconnected or have no dependents?" + ``` + `[github]` +4. Use relationship confidence tags. Every inferred edge is marked `EXTRACTED`, `INFERRED`, or `AMBIGUOUS`, so you can tell what was found in the code vs. guessed — `AMBIGUOUS` clusters are good places to look for confusion. `[github]` +5. For shell scripts (no AST support yet): ingest them as **documents** so the model does a semantic extraction instead of AST parsing. `[interview]` The creator calls shell scripts "flat" and treats document-mode as the temporary workaround. Note `.sh`/`.bash` *do* appear in the v8 supported-extensions list `[github]`, so behavior may have shifted since the interview — verify on your version. + +--- + +## Playbook 4 — Build a persistent "digital twin" / second brain + +The cross-project setup you actually want: one queryable memory spanning your code repos, documents, and a personal KB, kept fresh over time. The creator's framing is a "digital twin" that "gets smarter with time" via incremental updates. `[interview]` + +### Recommended structure: many local graphs, one global view + +Don't try to cram everything into a single monolithic extraction. **Build a graph per project, then fold them into one cross-project global graph.** This keeps each project's `--update` cheap and isolated while still giving you one place to query across everything. `[github]` + +1. In each repo / doc folder / KB vault, build its own graph: + ```bash + /graphify . # in a code repo + /graphify ./notes # in your personal KB / Obsidian vault + ``` + Code is free/local; documents and notes go through a model — use a **local backend** to keep this free and private (see [Playbook 6](#playbook-6--the-creators-day-to-day-workflow) and [05-local-models-and-backends](05-local-models-and-backends.md)). `[github]` `[interview]` +2. Register each project's graph into the global graph with a memorable name: + ```bash + graphify global add graphify-out/graph.json my-api + graphify global add graphify-out/graph.json my-notes + graphify global list # see all registered repos + node/edge counts + ``` + The global graph lives at `~/.graphify/global.json`. `[github]` +3. (Alternative one-step form) Extract and register in a single command: + ```bash + graphify extract ./notes --global --as my-notes + ``` + `[github]` +4. Query across the whole twin via your normal `query` / `path` / `explain` calls, leaning on god nodes to navigate. `[github]` `[interview]` + +### Ingest cadence (keep the twin from going stale) + +The user's real concern is assets going stale. Split the cadence by content type: + +- **Code — automate it.** Install the git hook once per repo so the graph rebuilds on every commit (AST only, no API cost), and `graph.json` auto-merges instead of conflicting: + ```bash + graphify hook install + ``` + `[github]` +- **Docs / KB / papers — refresh on demand.** These need a model call, so run them deliberately after you add or change material. `--update` re-extracts only changed files using SHA-256 hashing, so it resumes where it left off rather than rebuilding: `[interview]` `[github]` + ```bash + /graphify --update # or: /graphify ./notes --update + ``` +- **Re-register after a doc refresh** so the global view picks up the new nodes: + ```bash + graphify global add graphify-out/graph.json my-notes + ``` +- **Ingest in splits, not one giant dump.** The creator recommends splitting a large repo or document set and re-ingesting in pieces rather than pushing the whole corpus in one shot — it merges in more cleanly and avoids context dilution. `[interview]` + +### Pulling external knowledge into the brain + +Add papers and videos straight into a graph (videos transcribed locally via faster-whisper): `[github]` +```bash +/graphify add https://arxiv.org/abs/1706.03762 +/graphify add +/graphify add https://... --author "Name" --contributor "Name" +``` +`[interview]` describes this as turning a Stanford lecture or any video/audio into a queryable section-by-section map instead of re-watching it. + +--- + +## Playbook 5 — PR impact analysis + +For reviewing your own or a team's pull requests with graph-aware impact. Requires the GitHub CLI auth your repo already uses. + +1. See the dashboard — every open PR with CI state, review status, worktree mapping, and graph impact: + ```bash + graphify prs + ``` +2. Deep-dive a specific PR's blast radius: + ```bash + graphify prs 42 + ``` +3. Let the graph rank your review queue (auto-detects backend from env): + ```bash + graphify prs --triage + ``` +4. Spot merge-order risk — PRs touching the same graph communities are likely to conflict: + ```bash + graphify prs --conflicts + ``` +5. Scope it when you have many branches: + ```bash + graphify prs --base main # only PRs targeting main + graphify prs --worktrees # worktree → branch → PR mapping + graphify prs --repo owner/repo # a different repo + ``` +All `[github]`. To pin the triage backend (e.g. keep it local/cheap): +```bash +GRAPHIFY_TRIAGE_BACKEND=ollama graphify prs --triage +``` +`[github]` + +--- + +## Playbook 6 — The creator's own day-to-day workflow + +The distilled habit the creator described for himself. `[interview]` + +1. **Local LLM for documents.** Extract docs/notes with Ollama so it's free and stays on your machine — no cloud, no per-token cost: `[interview]` `[github]` + ```bash + graphify extract ./docs --backend ollama + ``` + Code never needs this (it's local AST already). Tuning for small GPUs: + ```bash + GRAPHIFY_OLLAMA_NUM_CTX=8192 graphify extract ./docs --backend ollama + GRAPHIFY_OLLAMA_KEEP_ALIVE=0 graphify extract ./docs --backend ollama # unload after each chunk + graphify extract ./docs --backend ollama --token-budget 4000 # smaller chunks for local models + ``` + `[github]` Full backend setup in [05-local-models-and-backends](05-local-models-and-backends.md). +2. **God nodes first.** Always open with the most-connected concepts to get the map before drilling in. `[interview]` +3. **Query the graph, not the corpus.** Prompt the assistant to *extract from the graph* — the graph is the context/memory. Never ask the LLM to read the whole corpus again. `[interview]` +4. **Always `--update` when ingesting new material** so a later query doesn't force a full re-read. `[interview]` + ```bash + /graphify --update + ``` +5. **Lock the query-first behavior in.** Register Graphify with your assistant so it consults the graph before grepping/reading files: + ```bash + graphify install # or: graphify claude install + ``` + `[github]` The creator notes he's working toward hard-wiring "go to the graph first" into the agent's behavior. `[interview]` + +--- + +## Token-savings note + +The interview's headline figures — "71.5x" in the README, with reports of "20x to 90x" from users — are **sales claims** and explicitly described as corpus-dependent with "no ceiling or floor." Do not treat them as guarantees. `[interview]` See [07-token-economics-and-updates](07-token-economics-and-updates.md). + +--- + +## Open questions / unverified + +- **Shell-script handling drift.** The interview says shell scripts aren't AST-supported and must be ingested as documents, but the v8 supported-extensions list includes `.sh`/`.bash`. `[github]` The document-mode workaround in Playbook 3 may be obsolete on current versions — confirm against your installed build. `[unverified claim]` +- **`graphify-out/` reuse across projects in the global graph.** Each `graphify .` writes to a local `graphify-out/`; the exact path you register with `graphify global add` matters. Confirm whether re-running `global add` with the same name *replaces* or *appends* — not stated in the README. `[unverified claim]` +- **`/graphify add` for KB sources** (arxiv/youtube) is documented `[github]`, but whether added external sources are automatically included when you fold the project into the global graph is unverified. `[unverified claim]` +- **Self-learning / domain-adapting "smarter over time" layer** and **Slack/Notion/meeting connectors** are described by the creator as in-progress/future, not shipped in v8. `[interview]` Do not build a workflow that depends on them yet. +- **Official site** (graphifylabs.ai) blocks plain fetch (403); documented workflows here are anchored on the v8 README rather than the marketing site. diff --git a/docs/graphify/09-best-practices-checklist.md b/docs/graphify/09-best-practices-checklist.md new file mode 100644 index 0000000..a4623ad --- /dev/null +++ b/docs/graphify/09-best-practices-checklist.md @@ -0,0 +1,126 @@ +# 09 — Best-Practices Checklist & Quick Reference + +The page to keep open while using Graphify (v0.8.30): a scannable do/don't list, a command quick-reference, a "many projects" setup mini-guide, and the common mistakes to avoid. Detail lives in the sibling docs — this card cross-links to them. + +> Provenance tags: `[interview]` (creator's intent/sales claims), `[github]` (verified repo facts), `[community]` (third-party), `[unverified claim]`. + +--- + +## Do / Don't + +**Do** + +- **Index code freely — it's local AST, no tokens.** Code (33 languages, tree-sitter) parses on your machine with no model calls. Run `graphify .` on any repo without fear. `[github]` `[interview]` — see [03-ingesting-code-ast.md](03-ingesting-code-ast.md) +- **Reserve the model (tokens) for documents/images/audio/video only.** This split is the #1 cost rule. `[interview]` — see [04-ingesting-docs-knowledge.md](04-ingesting-docs-knowledge.md) +- **Use a local backend (`--backend ollama`) for documents** to keep extraction free and private. `[interview]` — see [05-local-models-and-backends.md](05-local-models-and-backends.md) +- **Ask for god nodes FIRST, then scalpel down.** Read the top of `GRAPH_REPORT.md` for the architecture spine, then `explain` / `path` / bounded `query` into specifics. `[interview]` — see [06-querying-and-god-nodes.md](06-querying-and-god-nodes.md) +- **Prompt the graph, don't make the LLM read the corpus.** The graph IS the memory; have the assistant *extract from* it, not traverse it. `[interview]` +- **Always `--update` when adding data.** SHA-256 hashing + dedup re-process only changed files and merge in, instead of rebuilding. `[interview]` `[github]` — see [07-token-economics-and-updates.md](07-token-economics-and-updates.md) +- **Split large corpora and re-ingest in pieces** rather than dumping one giant chunk — cheaper and less hallucination/dilution. `[interview]` +- **Tune for local/small models:** smaller `--token-budget` (chunk size), lower `--max-concurrency`, raise `--api-timeout` if it stalls. `[github]` +- **Automate freshness for code:** `graphify hook install` (commit hook) or `--watch` — both AST-only, free. `[github]` +- **Measure your own savings with `graphify benchmark`** instead of trusting any headline multiplier. `[github]` + +**Don't** + +- **Don't quote a token multiplier as a promise.** "70x / 90x / 71.5x" are corpus-dependent marketing figures; independent testing shows ~1–49x, and net-*negative* on small repos (<100 files ≈ 1–3x; some users measure *more* tokens). Say "measure with `graphify benchmark`." `[unverified claim]` `[community]` — see [07](07-token-economics-and-updates.md) and [external-tips.md](external-tips.md) +- **Don't run your first build on a big doc pile with a cloud backend** — that's the way to burn your daily limit (one user burned theirs + $25–30 extra). Start on code, then add docs locally. `[interview]` +- **Don't expect `graphify query "god nodes"` to return the ranking** — `query` is semantic search; the structural god-node list lives at the top of `GRAPH_REPORT.md`. `[github]` +- **Don't confuse `--budget` with `--token-budget`.** `--budget N` caps a **query answer**; `--token-budget N` sets the **extraction chunk size**. Different stages. `[github]` +- **Don't expect the commit hook (or `--watch`) to refresh docs** — they handle **code only**. Re-run `--update` on docs manually (they cost tokens). `[github]` +- **Don't rebuild from scratch to add data** — use `--update`. Use `--force` only to overwrite/clear ghost nodes after deletions. `[github]` +- **Don't treat Obsidian as a substitute.** It's a nice visual pairing, but it can't cluster or surface cross-community links the way Graphify does. `[interview]` — see [01-overview-concepts.md](01-overview-concepts.md) +- **Don't get the package name wrong** — it's `graphifyy` (double-y), the binary is `graphify`. The single most common install mistake. `[community]` + +--- + +## Command quick-reference (v0.8.30) + +> **Invocation forms.** In-IDE uses the slash form (`/graphify ./path --update`) and borrows your session's model for docs. Headless uses `graphify extract ./path` and needs an explicit `--backend`. The `query` / `path` / `explain` verbs work both ways (drop the slash in a terminal; always use the no-slash form on Windows PowerShell). `[github]` + +**Install & register** + +```bash +uv tool install graphifyy # recommended (or: pip install graphifyy) +graphify install # register the skill with your assistant +graphify claude install # optional: make Claude consult the graph automatically +``` + +**Build / update** + +| Goal | Command | Cost | +|---|---|---| +| First build | `/graphify ./path` — or headless `graphify extract ./path --backend ollama` | code free; docs/images cost tokens | +| Add / changed data | `/graphify ./path --update` | only changed files re-processed | +| Rebuild, clear ghost nodes after deletions | `graphify extract . --force` (or `GRAPHIFY_FORCE=1`) | as a full rebuild | +| Richer inference | `/graphify ./path --mode deep` | higher (more LLM passes) | +| Auto-rebuild on commit (code only) | `graphify hook install` | free (AST) | +| Live auto-rebuild (code only) | `/graphify ./path --watch` | free (AST) | +| Measure savings | `graphify benchmark` | free | + +**Query (start at god nodes in `GRAPH_REPORT.md`, then drill down)** + +| Goal | Command | +|---|---| +| Semantic search, bounded answer | `graphify query "..." --dfs --budget 1500` | +| Connect two named nodes | `graphify path "A" "B"` | +| Deep-dive one node | `graphify explain "Node"` | +| Visual call-flow | `graphify export callflow-html` | +| Re-cluster (free, no re-extract) | `graphify cluster-only . --resolution 1.5` | +| De-noise god-node ranking | `... --exclude-hubs 99` | +| PR impact / review queue | `graphify prs` (`prs 42`, `--triage`, `--conflicts`) | + +**Local-model tuning flags** (extraction stage; see [05](05-local-models-and-backends.md)) + +```bash +graphify extract ./docs --backend ollama \ + --token-budget 4000 --max-concurrency 2 --api-timeout 900 +# Ollama env: OLLAMA_BASE_URL, OLLAMA_MODEL, +# GRAPHIFY_OLLAMA_NUM_CTX, GRAPHIFY_OLLAMA_KEEP_ALIVE +``` + +**Outputs** land in `graphify-out/`: `graph.html`, `GRAPH_REPORT.md`, `graph.json`, `cache/`. Backends: `ollama` (local), `bedrock`, `claude`, `gemini`, `openai`, `deepseek`, `kimi`. + +--- + +## Setting up across many projects (code + docs + KB) + +The pattern: **one graph per project, folded into one global view.** Keeps each `--update` cheap and isolated while giving you a single place to query across everything. Full playbook in [08-workflows-and-use-cases.md](08-workflows-and-use-cases.md) (Playbook 4) and the global-graph mechanics in [03-ingesting-code-ast.md](03-ingesting-code-ast.md). + +1. **Build a graph in each repo / doc folder / KB vault.** Code is free (AST); route documents through a local backend to keep them free and private (see [05-local-models-and-backends.md](05-local-models-and-backends.md)): + ```bash + /graphify . # in a code repo (free) + graphify extract ./notes --backend ollama # in a docs/KB folder (local model) + ``` +2. **Register each into the global graph** (lives at `~/.graphify/global.json`): + ```bash + graphify global add graphify-out/graph.json my-api + graphify global add graphify-out/graph.json my-notes + graphify global list # node/edge counts per repo + graphify global remove my-api # unregister + ``` +3. **Set a freshness cadence by content type:** + - **Code → automate:** `graphify hook install` per repo (rebuilds on commit, free). `[github]` + - **Docs/KB → on demand:** `--update` deliberately after adding/editing material (costs tokens; the hook won't touch docs). `[github]` + - **Re-register after a doc refresh** so the global view picks up new nodes: `graphify global add graphify-out/graph.json my-notes`. +4. **Pull in external knowledge** (papers, lectures — videos transcribed locally): + ```bash + /graphify add https://arxiv.org/abs/1706.03762 + /graphify add + ``` + +--- + +## Common mistakes + +- **Wrong package name.** Install `graphifyy` (double-y); the binary is `graphify`. `[community]` +- **First run = big docs + cloud backend → token burn.** Start on code (free), add docs with a local Ollama backend. `[interview]` +- **Expecting `query` to return god nodes.** It's semantic search — read the ranking at the top of `GRAPH_REPORT.md`. `[github]` +- **Mixing up `--budget` (query answer) and `--token-budget` (extraction chunk).** `[github]` +- **Expecting the commit hook / `--watch` to refresh docs.** Code only; re-run `--update` on docs yourself. `[github]` +- **Stale-node drift.** `--update` is known to leak stale nodes (removed symbols aren't always pruned); use `--force` to rebuild clean when the graph drifts. `[community]` `[github]` +- **Quoting a savings multiplier.** Corpus-dependent — measure your own with `graphify benchmark`. `[unverified claim]` + +--- + +Index: [00-README.md](00-README.md) · Concepts: [01-overview-concepts.md](01-overview-concepts.md) · Install: [02-installation-setup.md](02-installation-setup.md) · Community/skeptical notes: [external-tips.md](external-tips.md) diff --git a/docs/graphify/external-tips.md b/docs/graphify/external-tips.md new file mode 100644 index 0000000..fa90717 --- /dev/null +++ b/docs/graphify/external-tips.md @@ -0,0 +1,100 @@ +# Graphify: Community Tips & Independent Perspectives + +Outside-the-docs notes on [Graphify](https://github.com/safishamsi/graphify) (PyPI package `graphifyy`, CLI `graphify`, by Safi Shamsi) — gathered from third-party reviews, GitHub issues, and primary data endpoints. This file deliberately favors independent and skeptical sources over the official marketing, and flags where the two disagree. See also [07-token-economics-and-updates.md](07-token-economics-and-updates.md) and [02-installation-setup.md](02-installation-setup.md). + +> **Source quality warning.** Much of the "review" content circulating about Graphify (knightli, openclawapi, augmentcode, several Medium posts) reads like SEO/AI-generated echo: it *repeats* the official headline numbers without measuring anything. Five blogs quoting "58.3K stars" is one claim, not five corroborations. The only substantively independent skeptical source found is [roborhythms](https://www.roborhythms.com/graphify-review/), which actually tested. Treat everything else as restated marketing. + +--- + +## Community setup tips + +- **Install `graphifyy` with the double-y.** The PyPI package is `graphifyy`; the CLI it installs is `graphify`. Getting this wrong is called out as "the single most common installation mistake." [community](https://www.roborhythms.com/graphify-review/) Confirmed by the [official PyPI page](https://pypi.org/project/graphifyy/). +- **`uv tool install graphifyy` is the recommended path**, with `pipx install graphifyy` and `pip install graphifyy` as alternatives, followed by `graphify install` (or `graphify claude install` for Claude Code specifically). [official](https://pypi.org/project/graphifyy/) +- **Backends are now opt-in extras.** As of v0.8.30 the Claude/Anthropic backend installs via the `[anthropic]` extra; other extras include `pdf, office, google, video, mcp, neo4j, svg, leiden, ollama, openai, gemini, bedrock, sql, dm, chinese, all`. [official](https://pypi.org/project/graphifyy/) Install only what you need rather than `[all]`. +- **Commit the output for team sharing.** Outputs land in a `graphify-out/` directory (`graph.html`, `GRAPH_REPORT.md`, `graph.json`); checking these in lets teammates on any AI assistant share one graph. [community](https://www.augmentcode.com/learn/graphify-knowledge-graphs-ai-coding) +- **Don't trust every edge.** Relationships are confidence-tagged `EXTRACTED` / `INFERRED` / `AMBIGUOUS`; reviewers recommend reading that metadata rather than treating the graph as ground truth. [community](https://www.augmentcode.com/learn/graphify-knowledge-graphs-ai-coding) + +## Known gotchas & workarounds (with links) + +- **Some users measure *more* tokens, not fewer.** In [issue #580](https://github.com/safishamsi/graphify/issues/580) a user reports that after `graphify claude install`, Claude Code prefaces answers with "Let me read the Graphify knowledge graph first as instructed," reads `GRAPH_REPORT`, and consistently uses *more* tokens than asking directly — across multiple queries in one session. Two other users (`sumitparakh`, `spperforce`) confirmed the same behavior in the thread. **Status: the issue is closed, but no maintainer fix or explanation is visible in the thread** — closure does not equal resolution here. [community](https://github.com/safishamsi/graphify/issues/580) This is a direct, independently-corroborated contradiction of the token-savings pitch on small/medium codebases. +- **The agent can silently bypass the graph.** [Issue #1114](https://github.com/safishamsi/graphify/issues/1114) (closed, "help wanted"): the `PreToolUse` hook only intercepts `Bash` grep — it does *not* catch the `Read` tool, so the agent can just read files directly and ignore the graph entirely. roborhythms independently flags the PreToolUse hook as "silently broken on Claude Code v2.1.117 and later." [community](https://github.com/safishamsi/graphify/issues/1114) / [community](https://www.roborhythms.com/graphify-review/) +- **Git hooks no-op on `uv tool`/`pipx` installs.** [Issue #1127](https://github.com/safishamsi/graphify/issues/1127) (closed): `graphify hook install` silently does nothing for isolated-environment installs because interpreter detection ignored `.graphify_python`. If your post-commit auto-rebuild "isn't firing," this is likely why — check you're on a version after this fix. [community](https://github.com/safishamsi/graphify/issues/1127) +- **Stale nodes accumulate.** [Issue #1116](https://github.com/safishamsi/graphify/issues/1116) (open): `graphify update` leaks stale nodes — symbols removed from files that still exist are never pruned, so the graph drifts from reality over time. [community](https://github.com/safishamsi/graphify/issues/1116) +- **Code-only repos still demand an LLM API key.** [Issue #1122](https://github.com/safishamsi/graphify/issues/1122) (open): `extract` requires an LLM API key even for code-only corpora, despite code extraction making no LLM calls. Annoying if you wanted pure local AST indexing. [community](https://github.com/safishamsi/graphify/issues/1122) +- **The architecture-overview tool is itself a token hog.** roborhythms found the overview tool can return up to ~131,000 characters (~33,000 tokens) — a "hidden token trap" that can erase your savings on a single call. [community](https://www.roborhythms.com/graphify-review/) +- **Graphs are build-time snapshots.** They go stale and need manual rebuilds; this is the headline limitation everyone repeats. [community](https://www.roborhythms.com/graphify-review/) + - *Workaround:* keep `graphify update` in **git hooks, never per-turn AI hooks** — `graphify update` takes ~10s+ on a real monorepo and will "pile up, hang in the background, and saturate CPU/RAM" if wired to an AI turn hook. Use `graphify hook install` (installs post-commit + post-checkout, both backgrounded; post-checkout does incremental for ≤5 changed files, full rebuild otherwise). [community](https://dev.to/mir_mursalin_ankur/graphify-code-review-graph-build-a-self-updating-knowledge-graph-for-claude-code-and-other-ai-j1m) + - The same write-up reports real resource blowups — "3 stuck processes at 65–73% CPU each, load average 12+, RAM saturated" from rapid-fire commits — and adds CPU/RAM guards (`_resources_ok()`, `pgrep` guards, `timeout 300`) to its hook scripts. Worth borrowing if you commit frequently. [community](https://dev.to/mir_mursalin_ankur/graphify-code-review-graph-build-a-self-updating-knowledge-graph-for-claude-code-and-other-ai-j1m) +- **Legacy Java produces noisy communities.** roborhythms: "almost everything imports Logger," so god-node/community detection gets polluted on old Java codebases. [community](https://www.roborhythms.com/graphify-review/) +- **God-node centrality has been inflated by extractor bugs.** [Issue #563](https://github.com/safishamsi/graphify/issues/563) (closed) documented two extractor bugs that "systematically inflate god-node centrality" (rationale fragments + a calls-direction inversion). Fixed, but a reminder that god-node rankings have been wrong before. [community](https://github.com/safishamsi/graphify/issues/563) + +## The token-savings debate (independent takes) + +**The "71x" headline is real but cherry-picked — this is the most important independent finding.** roborhythms (Nathan Cole) tested across codebase sizes and explicitly debunks the viral number: *"The 71x figure comes from a single specific benchmark… It is real, but it is the upper bound on a curve that includes much more modest savings for smaller tasks."* His measured ranges: [community](https://www.roborhythms.com/graphify-review/) + +| Codebase size | Independently measured savings | +|---|---| +| Under 100 files | 1x–3x (negligible — "naive grep is already cheap") | +| 100–500 files | 6x–15x | +| 500–5,000 files | 30x–49x | +| 5,000+ files | up to 71x (but with build-time problems) | + +- **Strongest corroboration:** roborhythms reproduced a large-monorepo query at "about 123,000 tokens… Graphify answered in about 1,700" — i.e. the big-codebase savings are directionally real. A separate Medium author claims 71.5x on a 52-file corpus, but that number is implausible against roborhythms' "<100 files = ~1–3x" finding and should be treated as marketing, not data. [community](https://www.roborhythms.com/graphify-review/) / [community](https://medium.com/@shahsoumil519/graphify-vs-caveman-two-clever-tools-that-make-your-ai-coding-assistant-way-smarter-c6cd91378c59) +- **Strongest skepticism:** [issue #580](https://github.com/safishamsi/graphify/issues/580) — multiple users measuring a net *increase* in tokens on smaller projects, because the mandatory "read the graph first" preamble plus `GRAPH_REPORT` costs more than it saves. This squarely contradicts the official framing for small repos. +- **roborhythms' practical verdict:** install if your monthly token bill exceeds ~$50 on a 100+ file codebase; skip small projects. [community](https://www.roborhythms.com/graphify-review/) + +**Headline-stat verification (checked against primary endpoints, 2026-06-03):** + +| Official/marketing claim | Independently verified value | Verdict | +|---|---|---| +| ~43K stars (per task brief) | **58,848 stars** via GitHub API | Brief is stale/low; real count is higher. [official](https://github.com/safishamsi/graphify) | +| 500K downloads (per task brief) | **1,283,025 total downloads** via pepy.tech | Brief is stale/low; real count is ~2.5x higher. [community](https://pepy.tech/api/v2/projects/graphifyy) | +| 70x–90x token savings | 71x is a real *upper bound*, not typical | Misleading as a headline; true for huge repos only. [community](https://www.roborhythms.com/graphify-review/) | + +Note the context for the stats: the repo was created **2026-04-03** (GitHub API) — roughly two months before this writing — so 58K stars and 1.28M downloads represent genuinely explosive, viral growth, not a long tail. The numbers are large; whether the *token-savings* claims live up to the hype is the part that needs the asterisk. + +## Roadmap signals from issues/releases + +Release cadence is extreme (~123 releases, often multiple per day; current `0.8.30`, 2026-06-02). Themes from recent releases and open issues: [official](https://github.com/safishamsi/graphify/releases) + +- **Context-cost reduction is now an explicit goal.** v0.8.29 shipped "progressive-disclosure skill files reducing context load by ~47%" ([issue #1106](https://github.com/safishamsi/graphify/issues/1106)), and v0.8.30 added a "Read-tool graph bypass nudge" — a direct response to the bypass problem in [#1114](https://github.com/safishamsi/graphify/issues/1114). [official](https://github.com/safishamsi/graphify/releases) +- **Security hardening.** v0.8.29: local providers made opt-in, office/PDF screening, metadata-address blocking, file-bomb protections. [official](https://github.com/safishamsi/graphify/releases) +- **Cross-language depth.** v0.8.22–0.8.27 added type-reference and inheritance edges across Swift/Kotlin/PHP/Rust/Go/ObjC/Julia/C++/TypeScript; determinism fixes (stable community IDs). [official](https://github.com/safishamsi/graphify/releases) +- **Open pain points to watch:** stale-node pruning ([#1116](https://github.com/safishamsi/graphify/issues/1116)), API-key-for-code-only ([#1122](https://github.com/safishamsi/graphify/issues/1122)), hardcoded 600s claude-cli timeout ([#1112](https://github.com/safishamsi/graphify/issues/1112)), headless image ingestion reading images as garbage ([#1109](https://github.com/safishamsi/graphify/issues/1109)), and a requested direct-Postgres connection ([#1093](https://github.com/safishamsi/graphify/issues/1093)). + +## Alternatives people compare it to + +- **code-review-graph (CRG):** SQLite-backed AST graph with blast-radius analysis, embedding-based semantic search, ~25 MCP tools, and sub-second incremental updates — fast enough to run in a Claude `Stop` hook (unlike Graphify). One write-up runs the two together with a fallback chain "CRG semantic (miss) → graphify query → grep." [community](https://dev.to/mir_mursalin_ankur/graphify-code-review-graph-build-a-self-updating-knowledge-graph-for-claude-code-and-other-ai-j1m) +- **Caveman:** orthogonal, not a competitor — it compresses *output* ("~65% fewer output tokens") rather than input. Tip: pair them — Graphify on the input side, Caveman on the output side. Caveat from the same author: *"Graphify won't untangle a genuinely messy codebase"* and *"Caveman won't fix bad answers — it just makes bad answers shorter."* [community](https://medium.com/@shahsoumil519/graphify-vs-caveman-two-clever-tools-that-make-your-ai-coding-assistant-way-smarter-c6cd91378c59) +- **Understand-Anything (Lum1104):** a Claude Code plugin with a multi-agent pipeline that builds a per-file/function/class knowledge graph plus an interactive dashboard — positioned as a more visualization-first alternative. [community](https://github.com/Lum1104/Understand-Anything) + +## Open questions / unverified + +- **No genuine Reddit, Hacker News, X/Twitter, or LinkedIn primary discussion was found.** A targeted `r/ClaudeAI` search returned nothing indexed. The task asked to document community sentiment from these venues; I could not, and am declining to fabricate it. The substantive independent signal is concentrated in roborhythms + GitHub issues. +- **The "sharply divided community sentiment on contribution credit" / drama claim is NOT supported by primary sources.** roborhythms asserts it, but the one attribution-related issue I could read — [#799](https://github.com/safishamsi/graphify/issues/799) — is a third party being *scrupulously respectful* about crediting Graphify upstream, with **zero comments** and a clean close. That is the opposite of drama. Treat roborhythms' characterization as an unverified secondhand claim. [unverified claim](https://www.roborhythms.com/graphify-review/) vs. [community](https://github.com/safishamsi/graphify/issues/799) +- **No maintainer explanation found for the net-token-increase reports** ([#580](https://github.com/safishamsi/graphify/issues/580)); whether v0.8.29's ~47% context reduction actually fixes it is unverified — no independent re-test post-fix exists. +- **The 71.5x-on-52-files Medium claim is unverified and contradicts roborhythms' tested "<100 files ≈ 1–3x."** [unverified claim](https://medium.com/@shahsoumil519/graphify-vs-caveman-two-clever-tools-that-make-your-ai-coding-assistant-way-smarter-c6cd91378c59) +- pypistats.org rate-limited during checking; download total is from pepy.tech only (single source, but a primary endpoint). + +## Sources + +- https://github.com/safishamsi/graphify (official repo + GitHub API: 58,848 stars, created 2026-04-03) +- https://github.com/safishamsi/graphify/releases (official release notes) +- https://github.com/safishamsi/graphify/issues/580 (net token *increase* reports) +- https://github.com/safishamsi/graphify/issues/799 (attribution sanity-check; no drama) +- https://github.com/safishamsi/graphify/issues/563 (god-node centrality inflation bug) +- https://github.com/safishamsi/graphify/issues/1114 (Read-tool bypass / PreToolUse gap) +- https://github.com/safishamsi/graphify/issues/1116 (stale-node leak) +- https://github.com/safishamsi/graphify/issues/1122 (API key required for code-only) +- https://github.com/safishamsi/graphify/issues/1127 (hooks no-op on uv/pipx) +- https://github.com/safishamsi/graphify/issues/1112 (hardcoded claude-cli timeout) +- https://github.com/safishamsi/graphify/issues/1109 (headless image ingestion) +- https://github.com/safishamsi/graphify/issues/1093 (direct Postgres feature request) +- https://github.com/safishamsi/graphify/issues/1106 (progressive-disclosure context reduction) +- https://pypi.org/project/graphifyy/ (official package: v0.8.30, extras, Python >=3.10) +- https://pepy.tech/api/v2/projects/graphifyy (1,283,025 total downloads) +- https://www.roborhythms.com/graphify-review/ (independent tested review — the key skeptical source) +- https://www.augmentcode.com/learn/graphify-knowledge-graphs-ai-coding (echoes official stats; tips on confidence tags + team sharing) +- https://dev.to/mir_mursalin_ankur/graphify-code-review-graph-build-a-self-updating-knowledge-graph-for-claude-code-and-other-ai-j1m (self-updating hooks + CRG combo) +- https://medium.com/@shahsoumil519/graphify-vs-caveman-two-clever-tools-that-make-your-ai-coding-assistant-way-smarter-c6cd91378c59 (Graphify vs Caveman) +- https://github.com/Lum1104/Understand-Anything (alternative tool) diff --git a/graphify-interview b/graphify-interview new file mode 100644 index 0000000..f4331e9 --- /dev/null +++ b/graphify-interview @@ -0,0 +1,829 @@ +Graphify Interview Setup +0:00 +If you are using Claude Code, you've definitely heard about the new plug-in called Graphify, which is essentially a +0:06 +memory solution for all AI users. I already did a full breakdown on Graphify itself, so if you haven't seen that yet, +0:12 +please watch that here first. But this plugin already has over half a million downloads in just a few weeks that it +0:18 +was set up. And boy, do I have a treat for you guys today. You're going to have to excuse some of the audio mixups, but +0:24 +I have the creator of this plugin here live with me. And together on this video, I'm going to be asking him a lot +0:30 +of the same questions that you guys have in mind about this plugin. It's going to be interview style. We'll go through his +0:36 +best use cases, his inspiration on why he created this plug-in, and pinpoint the truth of whether this plugin can +0:43 +actually save you 70 times on token. So, without further ado, grab your cup of Joe, grab a snack, and let's get into +0:49 +this. All right, guys. I got Safi here with me. He is the creator of Graphify. +0:55 +And today we're going to go through some common questions, kind of reveal the intentions and inspiration behind +1:01 +creating this awesome plug-in. So Sophie, what I'd love for you to give us is an elevator pitch. I got some +1:08 +questions on my side, so you guys might see me looking over. Uh, but give us an elevator pitch, a TLDDR of what you +1:14 +currently do and how that work really led to the creation of Graphify. Hi guys, Sophie here, the creator of +Safi Elevator Pitch +1:20 +Graphify. So I'm I'm an AI engineer been working on knowledge graphs since over two years now. I've got two research +1:27 +papers on graph networks and then hybrid rock systems have combined vector +1:33 +databases with graph architectures and I've been working on the increasing the +1:38 +process memory systems of large language models and that's where the graphify came in as a link to my research and +1:44 +then my AI engineering experience. Yeah. So graphify actually started as a link +Origin Story Karpathy Tweet +1:50 +by from a post of Andre Karpati. Uh so he tweeted about like a structure when +1:56 +you can use raw data files and then you can extract them later on so that you can minimize the tokens usage of your uh +2:02 +coding assistants and that's where the idea the whole idea clicked in from my experience of have been been working on +2:08 +graphs. I shipped that feature within two days of Karpati's uh uh idea pitch +2:13 +on to X and that's how it all started and here we are with 500K plus downloads +2:19 +on Pipi and nearly 43 43K stars on GitHub. I +2:25 +absolutely wild how that actually all went down. Um what I'm trying to +Unexpected Viral Growth +2:30 +understand now right is like did you did you expect the kind of traction that you got when you guys when you initially +2:37 +launched this product? Was it kind of expected or were you really surprised? Oh, I'm totally humbled by this totally. +2:43 +So I I did think like it will go past 10k stars maybe because it was a need as +2:50 +a tool it was in need of an hour and the the timing was to totally correct and then right after fe of kapati I did +2:56 +expect like it should it will blow up a bit but not this far and and I'm totally humbled by this uh the the people the +3:04 +sgestions of people and then people have been using this and putting it publicly as well how they are using my my my +3:10 +software graphify they've been making posts on LinkedIn they've been making posted eggs and and pretty much uh what +3:17 +do we say I'm I'm in dilemma of like it's it's something I had never experienced before and I'm pretty much +3:23 +excited about this part. Yeah, that's key. You know, I I think before honor comes humility and keeping +3:29 +the humility is always key. It's what makes us likable and from what I've known you I've known you that this past +3:35 +month, you are a super humble guy and I think you deserve everything that you have coming for you. and looking at what +3:42 +we're looking at what for sure looking at where things have come like walk us through well not this part +3:49 +yet what I want to ask you is when you were looking at this was this you per like were you scratching a personal itch +3:56 +when you kind of put this together um was this was this aimed at a specific +4:01 +category do you did you have something in mind when creating this or was it more like you saw a problem you solved +4:07 +it and you were kind of like testing your skills Tell me a little bit about how that looked. So it all started as a personal as you +Personal Itch Memory +4:13 +told as I told you I'm an AI engineer. I've been working in this in this whole system since over two years now. So I've +4:18 +been facing the same problem of like losing the context once I switched from one session to another session and and +4:24 +and AI labs like anthropic and open are continuously working on fixing this problem of context when you switch from +4:30 +one session to another session and they've been giving a compact conversation feature as well. you must have seen and and the whole reason I +4:37 +came up with this idea was like let's do something into it. let's come up with a good good feature good good software +4:43 +that can fix this problem for just not me but for others as well that's necessary and I came up with the open source software idea to do this and then +4:50 +eventually when I saw people picking up my tool I I went full on it and then started shipping as fast as possible +4:56 +started integrating more features did some R&D and then went into production after that it's +5:02 +it's doing pretty well at at this point uh it's been like a month now and I've got like decent decent uh response from +5:09 +the audience Yeah, you definitely have gotten a really good um amount of traction on this. So, now that I have a +5:14 +little bit more of an understanding, which I get because that's usually where all things start and the the market demand was there. You know, we all knew +5:21 +it. Memory is a huge problem. It's what a lot of the AI users are looking at solving right now. Nobody has quite +Top Use Cases +5:27 +solved it yet. I wanted to segue into something that I think a lot of us are +5:32 +really curious about because there's beginners, there's intermediate, you +5:37 +know, uh, AI users, and then there's more advanced. And I want to know, you +5:43 +know, what are the what are the if you had to pinpoint the three best use cases of this product, maybe for a business +5:50 +owner, you an everyday college student, you know, like different categories of people, like what would you say are the +5:57 +top three use cases for Graphify in your head? Yes. So, let's say Graphifi's main +6:03 +criteria is it's it works pretty well with your coding assistance. Let's say you've got a new uh contractor employee +6:09 +who's going to come as a senior engineer in your in your company and then he wants to go through the whole codebase of your of your of the whole +6:15 +architecture of your company's codebase. So if he were to get in deep into the whole architecture it will take him like +6:21 +two days three days and plenty of slack messages to the previous employer or something like that. So just to prevent +6:27 +this whole scenario to come like to spark this whole scenario graphify it +6:32 +what it does is it creates a map of the whole codebase using abstract syntax tree a libraries it's it's free of cost +6:39 +as well there is no lms involved into it so it creates a map it creates god nodes +6:45 +and then it connects with the coh different parts of a codebase together and then you can pretty much pretty much +6:51 +easily understand them in one shot it saves you time saves you money. Let's say you you you are hiring someone for +6:58 +like $150 per hour just to go through your code base and you can ship that you can you can do that for free in like few +7:05 +minutes and it's a big ROI just by a tool. Secondly, uh let's say +7:11 +you are working for an enterprise and then there's a ticket on your back end some some users facing a problem right +7:17 +and then you want to fix that ticket as soon as possible. What are you going to do? uh maybe one of your engineers will sit or fix this for the whole day or two +7:24 +days or come up with a solution after 3 days right so to to like bring the time down here you all you have to do is you +7:31 +have got a brain here you got the map of the whole code piece you'll just look for the dependency and you will see how +7:37 +the dependency is connected to all other files in the same codebase and and it's one shot it's boom you've got the whole +7:43 +solution from there you can easily find the solution from the god nodes of the whole architecture thirdly uh so +7:48 +graphify isn't just about the code bases It's also there to create persistent memory. So we create a map of your +7:55 +documents, of your images, on of your YouTube urls, of your audios using whisper. So I'm converting all those +8:02 +videos and audios into transcripts and then creating those text from those transcripts in the form of a graph and +8:07 +you can pretty much retrieve everything. Let's say you had some lecture or you want to see you you want to prompt a lecture of of of Stanford let's say and +8:15 +then what you're going to do is just put that link get the get the lectures uh transcription and then you can have the +8:21 +map of the of the lecture with each section of the lecture divided into into +8:26 +pre various graphs and you can retrieve anything much from there. It saves you +8:31 +it saves you a lot of time like go through the whole video rather than like prompt the whole video in one shot. So +8:37 +it saves you time and money both of these things and gives you persistent memory as well. You can keep on adding context to the same graph time after +8:44 +time with less tokens rather than like making the coding agent go through the whole corpus uh or call multiple times +8:51 +for a simple task then going at once and then shipping you the final response. +8:57 +Right on. And what what I'm looking at is for me what's really really exciting +9:02 +is the ability to create the semantic relationships meaning the hidden meaning between the different assets that is +9:09 +super huge because when I have something searched in my clo my claude files it's like how does this file really connect +9:16 +to this file you know claude can search and find the different file names but I +9:21 +think a really good important use case especially on number three which is for everyday day-to-day users users. +9:28 +That relationshipbased mapping is absolutely huge. Now, what we're looking +9:35 +at is essentially a local rag system. You know, it it's a database. It's a way +9:41 +to look through all that information. And now with the development of of all +9:46 +these different plugins like GSD you know about you know you might have seen some of the stuff we've built internally +9:51 +on our side Paul and seed you have non-engineers non-developers building +9:57 +develop you know actually developing products so this is also a way for +10:03 +people to use these these plugins and these orchestration layers to build +10:08 +products match it with something that allows them to sift through their code bases more effectively with less tokens +10:16 +and and to have those relationships tied together creating a a way more effective +10:22 +and I even fun like I mean using these tools are so much fun just in exponentially increasing our +10:30 +output and our our capacities capabilities [snorts] so on that note +10:35 +let me pull up my questions again um so we understand I have something to say here uh that's +10:41 +the best best use case here. So there's too much of AI slop coming in. People are shipping fast using AI and they are +10:48 +actually aware what what's what they are shipping the code. There's a lot of junk code there. So what if you like map the +10:55 +junk code and then you can you can see what's what's wrong in your code as well by just using a small coding tool coding +11:01 +assistant graphify. So it can help the non-coders with no technical background as well to like retrieve and then fix +11:08 +their fix the issues with their code bases. And that's one of the use cases I I forgot earlier on. Yeah, there's definitely a lot of AI +11:13 +slop out there, bro. Um, so it it that question kind of tied into my next +11:19 +question, so I might not have to go deep into it, but maybe there's a uh specific +Business ROI Digital Twin +11:25 +ROI that you can outline. you know, for most business owners, most of my clients, you know, these are guys that +11:30 +are doing at least a quarter million plus a year in their business and they want to know, you know, because we've +11:36 +put out Charlie OS and that's, you know, oneclick install for claw code. You know, the frameworks, the file +11:43 +structure, you know, how important file structure is using clawed code internally. If that's not set right, +11:48 +like everything else is just going to be a mess. You you you need the right frameworks. So for those of for those of +11:56 +for those business owners that might be watching this or anybody looking to start a business um is there anything +12:01 +that you might have missed in terms of graphify like how how is this save we +12:06 +know how it's saving time but is there anything that you might have missed in what you said about the particular ROI +12:12 +financially for businesses in this case is there anything you want to expound on there yes so as an enterprise let's say uh you +12:19 +have hired a new person and then uh so basically The whole concept is about a digital brain. So we create a digital +12:27 +twin of your whole enterprise. Let's say uh see the context uh doesn't last for +12:33 +long. Either it says in your head or it says on Slack messages. It is people +12:38 +forget forget what they talked about yesterday. So graphify has a capability +12:44 +of giving you a persistent digital twin of your whole corpus which you can retrieve at any certain point of time +12:50 +rather than wasting your time and money hiring someone to search things for you or do things for you uh which you can do +12:57 +just by using your own coding assistance. So you're going to save a lot of like uh unnecessary money having +13:03 +been spent on employees doing very trivial task for you where you have your +13:08 +own digital twin your whole enterprise brain working also graphify has an incremental update feature which updates +13:16 +the whole graph automatically with every new injection of documents you have so +13:21 +it's an intelligent enterprise brain which gets smarter with time so I'm also +13:27 +working on a new layer of graphify which will make the whole brain smarter with +13:33 +self-arning layer I'm going to implement there so graphifi's brain will adapt to +13:38 +the users's use case like a certain domain let's say you are working in legal tech or rather you're working in +13:44 +real estate so the whole graph will start adapting as per your own requirements and that's my uh coming +13:50 +vision future vision is to help the enterprises as on bigger levels yeah I I love how excited you are about +13:56 +this product because a lot of the guys that I've been meeting on this journey, uh, posting on social media, it's only +14:02 +been about 5 months for me, but meeting you and seeing this product really, really push far and especially the one +14:09 +video I did, it has a little under half a million views. That was a huge accomplishment for me. Um, so thanks to +14:15 +you and your product, you know, I was able to accomplish that. So, you know, it's really exciting hearing about the +14:21 +new developments. I know you're very excited about the enterprise solution and I I think with the right push and uh +14:28 +hopefully guys if you guys are watching this and this gets enough traffic definitely like the video. If we get +14:34 +over a thousand likes on this video, he hasn't promised to do another video with me yet, but if this gets over a,000 +14:40 +likes, he might be tempted to do another one with me so we can go deeper on the workflows and see what he's got going +14:46 +on. Um, so anyways, the first version that dropped, right, and then we're +Whats New Since V1 +14:52 +going to go into something a lot of you guys are probably curious about, like +14:57 +how would a new user use this if you're starting from scratch? We'll get into that. Uh, but I want to ask you with the +15:04 +version one that dropped versus what you have now, what are some of the key differences that you've actually put +15:10 +into the news version that make this even better than when it first launched? Yeah, so there there are plenty of differences now. So I have given access +15:17 +to local backend system as well. So you can use Olama back end as well. Now earlier on it was just like you you were +15:23 +using CL cloud-based LMS which were given by your coding assistance like GPD or so models or like Opus models. So +15:30 +they were like causing a lot of problems to users on the burns of to burn of +15:36 +tokens. However, now you can call on your back end using llama uh local model +15:42 +as well the SLMs and it's pretty much cost effective and I've also got like 27 plus languages now earlier on we started +15:49 +with like 50 plus languages so we have gone past 26 plus languages or for the as you can extract a lot of languages uh +15:56 +coding languages now uh so backend system with uh a local local SLMs or LLMs and then uh with with more coding +16:04 +languages thirdly I have released another feature You can connect your Google workspace or even your AWS +16:10 +bedrock models there with graphify as well. Now it's it's a big solution for the enterprises they were looking for. +16:16 +So you can even collect bring your documents from Google workspace directly into graphify create a map of those +16:23 +documents and then you can retrieve whatever you want. See the relationships on your offse as well if you want. It's +16:28 +more interactive. That's crazy. And visually appeal. Yep. I I I'm using GWS CLI. It used a +Local Models And Privacy +16:35 +term called SLM. I'll have to research that. I know what LLM is. What is that? Small language model. Yes. All right. That makes sense. +16:44 +So basically large language models do not fit in smaller RAM size. So you need larger RAM or so GPUs like CUDA kernels +16:52 +to fit them in. So rather than like going for LMS, you can just go for SLMs. And SLMs are the future by the way +16:57 +because everything is going to be local and and that's what people are keen on. so that their data isn't shared to cloud-based LLMs in the future. And +17:03 +that's my vision is at the moment. Yeah. The the the good news is that the uh the small language model, the local +17:09 +stuff is not any worse. Yeah, it's a local first AI memory system. That's what Graphy will be in +17:15 +coming days or months. Pretty much none of your file will be shared with cloud-based LMS. It'll all run locally +17:22 +on your system. And that's the best uh win for the enterprises in the coming days. Yeah, that that's exactly what I'm +17:28 +what I'm seeing is when we get to a point where the large language models become they're going to keep getting +17:34 +better, right? Always better and better. But what's going to happen as a byproduct is that these small local models, this is the worst they'll ever +17:41 +be and they're only going to get better. So, a year from now, a small language model locally hosted might be as good as +17:48 +Opus 4.6 or maybe two years. I don't I don't know. What would you say like when are we going to have a local model as +17:54 +powerful as let's say Opus 4.6? six or 4.7 like what is your take on that perhaps maybe a year or so with the pace +17:59 +we are moving forward I think so we are going to have pretty smart SLMs pretty soon so basically what I've done is I +18:06 +I've fine- tuned SLM for my use case and they work decently well as as large +18:11 +language models as well so it's like how could you fine tune your SLMs for your use case so what I want to ask you now is I want +New User Setup Tips +18:19 +to look at what do we uh what would be the best way for a new user +18:25 +maybe who's never used this before to effectively set this up, you know, because I know the biggest for me was +18:31 +like I set it up and it ran through my whole daily limit and then I I spent like an extra like 25 or like 30 bucks +18:38 +off of and I'm on the $100 monthly plan with with Claude. Um what would be the best way to effectively run this without +18:45 +killing your whole limit and just exceeding it? Like what would you recommend? would you say um one of the +18:50 +gentlemen I did an onboarding call with before this he's like do I uh do I +18:56 +pretty much like say x amount of files do create a handoff do the rest of them do I just power bang you know my whole +19:04 +database um and am I even ready to run graphify for a new user it's like is it is it +19:10 +effective for them to do it with nothing in their codebase especially if they're not like developing things that's uh +19:16 +that's a lot I just threw at you um but does That question makes sense. The main problem if you are running if +19:22 +you are calling an LLM to parse your code base that doesn't make sense at all. I've given I' we have got like a +19:28 +there. So so you don't have to like call a cloud-based LM rather than like it's free of cost. The a call is free of +19:35 +cost. There's no API call included for an LLM. So a pretty work pretty much well for the code bases. You have to +19:42 +call the LLM back end only for your documents. Abstract syntax trees. It's a free Python library which can connect +19:49 +various parts of a codebase like functions and all of those sections of a +19:54 +code all together and create uh relationships between them in different files even in multiple repository. So +20:01 +it's it's free of cost. So basically what you have to do is with the new feature I've added in graphy with backend system is Olama. So you've got +20:08 +Lama as well as a back end which is free of cost as well. you've got locally running LLMs or SLMs for you or using +20:15 +Olama's API. Uh so what you have to do is call the code base using as which +20:21 +which which works pretty well for my even doers as at the moment and then if you have some documents you can use an +20:26 +LLM. So which creates a semantic extraction of the corpus of the of the chunks within a document and that's how +20:33 +you can save a lot of money. Secondly, when you are querying that the the graph the map, make sure that you first ask +20:41 +you you prompt to give you the god nodes from the whole corpus first of all. So so if you have large amount of god nodes +20:48 +that means that something has gone wrong with the cohesion or or maybe with your codebase. Uh if you are looking for an +20:54 +extraction of your codebase as well. uh and if you have a a decent number of god notes maybe for documents as well things +21:00 +have worked fine and then you have the whole architecture ready right in front of your eyes of even of your documents as well of your codebase just by +21:07 +prompting for god nodes and secondly from god nodes you can easily see where you have to prompt and write to minimize +21:13 +as much tokens as possible uh third also if when you are like ingesting more data +21:20 +make sure you use the word uh update as well graphy update so that it doesn't like start fresh from the beginning +21:26 +rather than I've used hashing strategy h 256 in here so it will start from where +21:32 +it left and then I've also got some dduplication techniques so there will be very less collusions of the entities +21:38 +within the same document or multiple documents so I've taken everything uh taken care of everything all you have to +21:44 +do is follow the right tactics for the right hooks I have put in the readme file or maybe you can just ask cla code +21:50 +to explain how to make the best use of graphy uh as the initial shot and then you work from there as well as a as a +21:56 +work tree workflow for for your whole use cases. Yeah, that makes sense. Yeah. So, it's a always remember as for +22:02 +code bases, LLM's for documents, extract backend using llama or if if you want to +22:08 +save cost or if you want to go with all your cloud-based LLMs, you can choose cloud code, gemini, openis, any of the +22:15 +models GPD. Uh and then after that always go for the god nodes and from +22:20 +there you can work work through into anything. Also make sure that you don't have to like when you are prompting the +22:25 +graph don't ask the LLM to go through the graph rather ask the LM to extract from the graph. So graph is the memory +22:33 +graph is the context. So always make sure and you can work around a bit and I've seen people so there is no ceiling +Token Savings Reality Check +22:39 +or floor in token uh savings here. What I've got 71.5 in my read me is for the +22:47 +repository I tried on and I've totally mentioned that it I've seen people who are getting like 90x token reduction in +22:54 +their retrieval as well and there are people who are getting 20x token reduction in their retrieval. So it's totally corpus dependent and and there +23:01 +is no ceiling or floor here. You know what's interesting? I have a lot of hate in my comments and I'm sure +23:06 +you've seen it. Oh 70 times what are you out of your mind? I'm like, "Guy, relax." Like, all these all these +23:14 +different situations are circumstantial. It's like from what you're saying, +23:19 +right? You and let me let me just let me can I I'm going to try to put this in layman terms because, you know, you're you're a +23:25 +super smart guy. For me, a lot of what you're saying, I'm reading in between the lines. Like, I hear big words and I +23:31 +chalk it up to like, okay, that he's just saying like as for code. So if if +23:38 +uh GSD builds an app, okay, that's perfect for that. So in a n like if you +23:43 +had to explain it in like an an to a ninth grader, you know, as having it +23:50 +look through codebase, great. Using um you said use an for your documents +23:57 +and you mentioned uh llama back for documents which are also free of cost now. So it it gives you a +24:04 +local model running on your own RAM on your own whole machine rather than calling a cloud-based LM. And I and I know that a lot of this is +24:11 +already hooked into Graphify. So if you guys have any questions on this, you guys can drop a comment below. And what +24:18 +I would suggest to get the best use or to get the best out of this, take the +24:23 +transcript of the video. What are you waiting for? plug it into your clawed code and when you guys are setting up or +24:29 +using Graphify, this is going to be perfect for you guys and um I think this is going to be great for anybody looking +24:35 +to use Graphify. So, on that note, I I I want I don't want to take up too much +24:40 +more of your time. I know you're excited about the growth. You know, I can go on to the the marketing side. I don't think +24:46 +you need help with the marketing right now. That's it's exploding on its own with the uh the creator outreach. So, we +24:53 +talked a little bit, maybe we didn't, about the uh the future of AI memory. +24:59 +So, there's two more questions I want to ask you. And then there were some some of my actual followers and school users +25:07 +that had particular questions and that isn't actually super long. Um, but +25:13 +before I get into these two questions, I just want to expound on what he said because he said something super +25:19 +important here. Sophie Safi Sophie was saying that each of these situations +25:24 +when you're using Graphify, it's circumstantial. There's no floor. There's no ceiling. So now when you guys +25:32 +are using this tool, it's dependent on how you're leveraging it. That's how you're going to start seeing +25:37 +the savings. So if you're not following this this playbook here, you know, he's +25:43 +talking about god nodes. It's like highlevel uh nodes, the god nodes, right? If you guys aren't leveraging +25:50 +that and knowing how to input that when using claude, it might be running and looking into all the specific nodes. So +25:56 +if you want highle information, you can then scalpel like go into the graph and get the information you need with those +26:03 +semantic relationships tied in. So the proper understanding and context and +26:08 +what he's saying of 70 times usage is key when understanding whether that's +26:14 +actually valid or not. So, I just want to leave that there and I want to tie +26:20 +into the next two questions here before we go into the the user questions. Where do we see the future of AI memory going? +Future Of AI Memory +26:27 +And I just want to hear your thoughts there and I want to understand after you share that, what is the biggest takeaway +26:35 +you're trying to give a user who's watching this video? what is the biggest takeaway you can give them that'll 20 +26:41 +times output their usage with with their their language models maybe let's just say cloud code so two questions there +26:48 +yep so the current future uh with AI memory uh always be a problem to be +26:55 +honest if you have worked with the whole structure of how neural networks are set and how retrieval systems work so +27:02 +basically there are some people some startups who are working on the same problem like super memory they are based in SF hydrab And then there's another +27:09 +thing called Gbrain by Gary Tan who is also working on the same problem of large context for LLMs and and and it's +27:17 +the market is very bright in in in person memory systems and I believe +27:23 +there's too much to come in next three years and uh the problem will never be solved until unless we have a new +27:29 +architecture other than transformers which are the base of NLM at the moment +27:36 +because there always be hallucination there there will always be a loss of context and uh they but they they never +27:42 +will be 100% efficient as as a human and that's something uh will always exist +27:48 +and persist but you can always optimize with the right tools with the right techniques as I said graphy is one of +27:54 +those tools if you optimize it the right way you can always have a persistent memory of your code base of your +28:00 +documents with incremental updates and features okay now I hear you on that I think how +28:05 +we use things will row like how much MPG in a car miles per gallon that has we're +28:11 +never going to get unlimited miles per gallon but we can always raise that ceiling. We can change the source of the +28:18 +gas you know the the the power source from gas to battery. We can extend those +28:24 +miles with different uh infrastructure and and setups. So I see where you're +28:30 +going with that and I wouldn't disagree at all. So what what would be your biggest takeaway like to anybody +28:37 +watching this? What do you want them to know that's in your brain that would allow them to use graphify and totally +28:43 +just change like total game changer using graphify? What would that takeaway be? +28:49 +Takeaway would be first of all you should know what you're putting into the whole system and if you're putting +28:54 +codebase you should always aware that graphify has uh in there so you have to like uh spend your tokens just to fetch +29:01 +the the code base. So, play it smart. Uh, and then you can have a lot of savings in there. For documents, maybe +29:07 +use a as I said earlier in in the interview as well. You can have a SLM +29:13 +now working for you using Llama. Uh, and it's free of cost as well rather than like going for a cloud-based LM that +29:19 +takes a lot of money. Secondly, you can split your repository or your documents as well and then you can reingest them +29:26 +uh in a way they they will just get added in the best way possible rather +29:32 +than like putting the whole chunk of documents in one shot. So basically we say that claude has 1 million of context +29:39 +and everyone is going towards like maximum millions of context in in one session right but it doesn't make sense +29:45 +at all. the more the context would be there will be a massive chance of +29:52 +hallucination or dilution in the reasoning as well and that's where you lose and that's where the whole graphite system comes in. So graphify isn't just +Neuro Symbolic Graphs +29:59 +uh supporting neural networks it's giving a s it's giving a a rise to neurosymbolic AI systems where you have +30:06 +a map or symbols to support the neural networks to come up with a response. So, and that's the whole graph vision is +30:13 +neurosyolic AI. Neuro symbolic AI. I love that. I it it's a way to simplify the language of +30:22 +the data being processed in a way that makes it efficient and and more relatable. No, +30:29 +not really. Yeah. So, neural networks, right? And then neural networks can +30:35 +hallucinate as well. So all the retrieval all of those uh path pathways +30:40 +can can hallucinate any response. So to make this whole problem uh with solvable +30:47 +we have symbols. So symbols are in the form of graph structures and then if you go deep dive into this graph theory +30:53 +you'll know about the new symbolic AI systems and even graphs also can give you an opportunity of clustering various +30:59 +communities in there which other tools like obsidian would never would never able would never give you like I've seen +31:06 +like some people are asking can't we just like make obsidian do do this and that it's not possible at all obsidian +31:13 +can't do clustering for you obsidian can't do cross community interaction for +31:18 +it will just give you an visualization which is which looks pretty much well but there is nothing credible you can +31:25 +take from there so you always need you always need a new symbolic structure or a tool that can solve it for you in one +31:31 +shot and that's where graphy is yeah I love that because that was literally what what a lot of my guys are +31:36 +saying to me bro they're like well can I just use obsidian by itself but this is +31:42 +this is basically putting in a way that makes sense like when it's in graphify it's just ass is this is just what +31:49 +already is existing versus having it organized and sifted through with your +31:54 +tool. So, I love that. I think you hit the nail on the head with that. And what +31:59 +I want to look at, you know, we we talked briefly now about the +32:04 +uh I'm working on another research for graphify, but I'll be doing hyperbolic embeddings uh using point ball theory, +32:12 +which is a pretty much a famous problem in mathematics from 2002. So this will +32:18 +solve the problem of retrieval hierarchal retrieval as well. So basically when they are god knots on top +32:24 +so they are baby nodes the child nodes at the bottom and then when you when you go down into into a tree there's always +32:31 +a context drift. You lose the context the more deep you go into a tree. And to solve that problem, I'm working on +32:36 +hyperbolic mings which will give you an exponential +32:42 +downward flow into a graph into a tree without losing context. And I think I will be implementing this whole research +32:49 +uh what I'm doing with graphifi's code base as well which will help and +32:54 +leverage the use cases of my users currently on on the open source side as +33:00 +well. Yeah. What what we're going to have to do man is when you come to the states we'll have to meet up. Um, I'd love to +33:06 +do like a um even if it's maybe I'm I'm gonna be in Florida at the time. I don't know when you're coming, but if we have +33:11 +something upstate in New York or something in New Jersey, uh what we could do is we can plan ahead. We can +33:17 +invite people out. We can maybe rent an area kind of bring some awareness next month because I' I've won a +33:23 +hackathon last last week and they are taking me to SF uh maybe in June or July +33:29 +something. Okay. Yeah. Well, whenever you come, man, we we'll have to figure that out because I I definitely want to do some local meetups. Uh but to kind of wrap +Obsidian And Shell Scripts +33:36 +this thing up, I have some um some basic questions here. We talked briefly about the Obsidian overlap. Um it's not a hard +33:44 +dependency. We know that it it is I I would say it's a decent recommended +33:51 +pairing because it's visual. Yes. Contact people obviously I think is is +33:57 +is a decent way of visualizing your stuff. and then it totally makes it more interactive rather than like going +34:03 +through the whole just on files and then extracting stuff. Yeah. Yeah. I I would agree with that. +34:08 +Um we know that Obsidian by itself is not going to get the best out of their data. Um so I what I want to ask you is +34:17 +we talked about the token economics that was a big question. Um something anal ad +34:23 +in my school he asked why does why does graphify not support +34:28 +scripts shell scripts are very flat I think I believe and they're very indiscriminatory I would be adding those +34:34 +as well in the future but for now if you want you can just pass them to an LM so what LM would do is rather than like going with an A which isn't capability +34:40 +at the moment for shell scripts what you can do is just put those as documents and then make the LM do a semantic +34:47 +extraction of a shell script so it'll be able to fetch you all the nodes from there. That's a that's a fix for now, a +34:53 +temporary fix. I'll I'll get it sorted maybe in coming releases so you can have shell scripts as well in there. But to +34:59 +me, shell scripts are a bit flat and that's the reason I didn't put them in the beginning. If if it's a requirement, it's a hard requirement, I I'll for sure +35:06 +put that in and I'm I'm more open for PRs and issues being submitted on the GitHub repository. I I I fix them on +35:13 +time and I'm pretty much active at the moment. Bro, I know you're always moving. every time I talk to you, you're always you're +35:19 +always moving. Um, so we kind of we kind of hit briefly, right? Like what would you do in your first three minutes of +35:25 +Graphify with a fresh uh client codebase which you've never seen? Which views or +35:30 +curies do you hit first to decide whether the architecture is sane versus a landmine? +35:35 +Yes. So you're talking about codebase, right? Mhm. Let's say you got a new hire as I +35:41 +told you in the beginning as well who has never seen the architecture and then you have been running graphify on your +35:46 +own code base even of on your multiple repositories of your whole enterprise where it has been incrementally +35:51 +incrementally updating the nodes and even the god nodes even in the child nodes and then clustering them even +35:58 +merging or connecting various communities together how they are dependent on on various dependencies in +36:03 +the codebase. So it's pretty easy for a new hire or maybe a new contracted senior engineer who wants to go to the +36:10 +code base and then have a look at the at the whole arch whole band architecture in in one shot, +36:16 +right? And I I think it's pretty self-explanatory when it when it's ran. It's like you're best off just running it through and kind of just seeing the +36:23 +output. I mean, if you have a subscription, it's not like you're paying for API cost. So yeah, that was a great answer. Um token economics we've +36:30 +went through. Um, for the people who have asked why is it that they're not seeing any token savings, it's because +36:36 +of the way that you're using it. We we if you know we've discussed that earlier in this video. Um, so I think token +36:43 +economics practical first run obsidian overlap we've went through. Um, and the +Workflow And Connectors +36:50 +last question is what is your current workflow like? What is it that you do like using this tool? Like what's your +36:56 +day-to-day look like with graphify for yourself? So current workflow is uh as I as I said I've been using local lms +37:03 +since earlier days but the thing is I didn't put them in since I was doing some hardcore testing if local are going +37:09 +to work good in a good way or not and and I've seen after some testing it's +37:15 +working working pretty well. So for the documents as I mentioned earlier on as well so you you use a local lm and then +37:21 +you can extract the information from there. Also by the way I'm adding a connector to various uh even even your +37:27 +one node even your slack I'm working on connectors as well. So you can connect your slack messages and then you can +37:33 +have them uh as as a map as well from from now onwards in in the coming +37:39 +releases even your slack messages even your meetings the meeting transcripts +37:44 +everything will be in a brain and as and you can work as an enterprise it will be on one short retrieval. So my current +37:50 +workflow is as I said local LM for the extraction and then always go to the god +37:56 +nodes first and then start retrieving from there and make sure you pron the graph and not like the LLM to go through +38:02 +the whole corpus once again and that's one thing also I'm adding some more features so that the the like the the +38:10 +agent would be hardcoded or hard configured to go through the graph first +38:15 +rather than doing anything else. what if what respect to what you prompt when graphy is active in a session and that's +38:21 +something I'm I'm looking forward to as well. Yeah, I I think finding a way to properly get it to work maybe via a hook +38:28 +or maybe in the cloud MD those instructions [clears throat] with it effectively like if if there was a way +38:35 +to have that integrated with an optimized [clears throat] flow to save tokens and it worked great like that +38:41 +would be phenomenal. I think some of the for me at least right now it's like anything the static information the +38:48 +information in your codebase or for me using it as like an operation center like my clients my data like everything +38:54 +and anything I I do I have MCPs CLI tools but my assets become stale over +39:00 +time so the process of having to remember to you know groom your data and go through a lot of that does +39:06 +[clears throat] um for most people um become a little bit of a constraint. So I'd love to see you know a lot of these +39:12 +things that you're doing over time to solve. I know always one more thing just hit my brain always make sure you update you you you +39:20 +put graphy update as well when you are like ingesting new files or code bases or documents as well. So make sure that +39:27 +it gets the right injection rather than when you you ask a question it doesn't have to go through the whole code once +39:33 +more. So you have to like update it as well. some of the techniques. Uh maybe I can share you a file and then you can +39:39 +share it with your audience as well. Like the best way of using graphify would be pretty much helpful like the +39:45 +way I do from the creator itself. What I want to do and I didn't mention mention this earlier but he's dropping a +Book And Final Thoughts +39:52 +book or he already has it out your new book. Yeah, it's out on gum road. It's called the memory layer. So it it talks about +39:58 +the whole journey as well how I've been working on graphs and also tells you about how graph has been in in like in +40:05 +computer science you can you can learn about knowledge graphs and graph theory spectral graph theory the matrices the +40:10 +llassian matrices and everything the community detection strategies using clustering algorithms lead in low vein +40:17 +so everything every theory about graphs is there and I think it's it's a it's a +40:22 +much must something must you can go for the link is going to be in the description below +40:28 +And if you did have an additional PDF or playbook that you put together, I can host it on my website. Um, so if you +40:35 +guys check the description, the book will be there. I might have a resource depending on, you know, whether he wants to drop that sauce or not. Um, but I +40:43 +know Sophie, Sophie, I know you're busy and you've answered so many questions +40:48 +for me personally. I'm going to take this transcript and throw it into my quad so that I can self-improve. What I +40:55 +love what you're doing is connecting the different like grid AI transcripts or you're you're pulling in Slack and +41:01 +you're creating you know nodes for that and you're going to create that on like an enterprise level. I think that's +41:08 +absolutely huge and [snorts] I think there is going to be a lot of ways for us to collaborate in the future. Uh but +41:14 +I don't want to hold you up. So if there's anything that you want to add that you want to leave people with +41:19 +before we conclude this thing I I would love for you to you know share your last words again I know you're busy so floor +41:26 +is yours so to other fellow developers I just I've just got one thing to say you can +41:32 +just do things and if you just have like the best determination in you that's it +41:37 +you can just do things yeah we could just do things with Claude now the best way to put it so guys uh if +Wrap Up And Goodbye +41:44 +you can please like the video. Subscribe if you like the kind of content that you're seeing here. And we're going to +41:51 +Sophie and I are going to try to do some more videos together if he's got time. But I'm also going to link his social +41:57 +medias below. We'll link Graphy. Um but again, everybody just leave a comment below. Thank him for joining us here +42:04 +today because he's really busy. He's doing a lot of great things in the AI memory space and you got to remember his +42:10 +name. You got to remember this guy. He's going to go far. So Safi, thank you for joining us, brother. Greatly appreciate +42:16 +you. Thank you so much, Charles, for having me here as well. All right, brother. diff --git a/memory-systems-compared060326 b/memory-systems-compared060326 new file mode 100644 index 0000000..b4d36cd --- /dev/null +++ b/memory-systems-compared060326 @@ -0,0 +1,326 @@ +Chapter 1: Intro: The 6 Levels of Claude Code Memory +0:00Right now, if you search for the best claw code memory system, you get absolutely buried. Mem zero, Carpathy's +0:066 secondsObsidian Wiki, Open Claw and Hermes, Mem Palace, Light Rag, Clawude Mem, Claw Mem. It's getting ridiculous to keep up +0:1515 secondswith it. But after spending hours researching it, these aren't competing tools. They're different ways of handling memory depending on your use +0:2222 secondscase. And the reason I went deep on this is because I've been building out my own agentic operating system. basically a business brain that runs across +0:2929 secondseverything I do. So, I needed to figure out what actually works, what scales, and what just adds complexity to my existing setup. So, in this video, I'll +0:3737 secondswalk through six levels of memory that build on top of each other, all the way to systems that work across every single AI tool that you use. So, by the end, +0:4545 secondsyou'll know exactly which one makes sense for your use case and which ones you can completely ignore. But before we go ahead through the levels, one thing I want you to know now because it will +0:5454 secondsmake the rest of the video easier to follow is that every memory system is answering exactly the same question. +1:001 minuteWhen you give claw code a task, how does it pull the right context at the right time? So the difference I'm going to show you between each level is just two +1:081 minute, 8 secondsthings. First is where your memory lives. So it's going to be the storage mechanism for your data and what the file structure looks like, whether it's +1:161 minute, 16 secondsmarked down or stored as vectors, for example. And secondly is how Claude actually gets hold of that data, which is just the retrieval stage. So some +1:241 minute, 24 secondsstuff's going to get copied into Claude's context automatically. Some stuff is going to sit in a database and get searched exactly when it's needed. +1:311 minute, 31 secondsSome stuff's going to live on your laptop. Some's going to live on the cloud, etc., etc. So let's jump now into level one. So you can think of level one +Chapter 2: Level 1: What Ships With Claude Code Natively +1:391 minute, 39 secondsas the native stuff that ships inside claw code. So most of you have already heard of the claw.md file. Some of you +1:451 minute, 45 secondshave heard of memory.mmd, but very few people are actually using both together properly. So, let's do claw.md first. +1:531 minute, 53 secondsAnd as most of you know this one already, I'll keep it quick, but it's effectively a plain markdown file inside your project folder where you store your rules, stuff about your brand, things +2:022 minutes, 2 secondsabout how you work with clients, coding style, and it's always loaded into every single session you pull up inside the terminal. You can think of it like a +2:102 minutes, 10 secondsnote that is just at the start of the context, almost like a system prompt that you're giving to Claude. So you can actually have this at the Claude project +2:172 minutes, 17 secondsfolder level to pass to all of your Claude instances. You can have it slightly lower at the root folder level if you have multiple projects which sit +2:252 minutes, 25 secondswithin the same folder. Or you can even have it in the individual project level for specific project instructions. The lower down the folder structure you go, +2:332 minutes, 33 secondsit still inherits the parent claude.mmd, but any conflicting rules, it will always take the local claw.md as gospel for specific project level instructions. +2:422 minutes, 42 secondsBut here's the thing that most people actually get wrong with their claude.md. +2:452 minutes, 45 secondsAnd I've seen this a lot, which is stuffing too much into the claude.md. So putting in your full brand guide, your tone of voice document, your complete +2:532 minutes, 53 secondsclient list. Think about when Claude actually starts a session every single time. It's going to burn through that context window reading all of it. So yes, it's important context, but only when you load it in at the right time. +3:033 minutes, 3 secondsAnd this is exactly the problem we're trying to solve called context ro. So this is the inability for AI and LLM models to actually recall 100% of the +3:123 minutes, 12 secondsinformation that we've loaded in as we increase the amount of context that's loaded in in the first place. So as a general rule of thumb, keep your claud +3:193 minutes, 19 secondsunder 200 lines. And then if you've got more context like a brand voice document then you can put that in a separate external file that's referenced from the +3:263 minutes, 26 secondsclaw.md and therefore it will only pull it in at the right time when it needs it. So the second built-in memory system inside claw code already running on your +3:343 minutes, 34 secondsmachine is called automemory and that forms a memory.mmd file. So you can jump into an existing project folder to see this best and what you can do is type in /memory. +3:443 minutes, 44 secondsYou'll hit enter and you'll see there are a few different things. There can be imported memory if you're using a separate memory system and we'll come to separate memory systems. You've got +3:523 minutes, 52 secondsproject and user memory which are effectively your claude.md files at different levels in the root folder. +3:573 minutes, 57 secondsWe're going to open up the automemory folder. You'll see that we have on a per project basis effectively a memory structure with an me memory file. So if +4:064 minutes, 6 secondsI open up all these files inside the memory MD file, we effectively have an index of lots of different memories that claw code can actually reference and +4:144 minutes, 14 secondsopen up other files of. So it's not just dumped a a huge amount of memories in here. What it's done is said on a project basis, we've got a specific +4:224 minutes, 22 secondsproject level feedback and on a more general scale, we've got a bunch of different feedback for specific things that it can refer back to kept as +4:314 minutes, 31 secondsseparate documents. It's following exactly what we've talked about, which is don't just dump more than 200 lines in a single file. Always reference a +4:394 minutes, 39 secondsseparate file and treat the memory MD or the claw.md as an index and then point to another file. So for example, we've got here a file that's feedback on +4:474 minutes, 47 secondsproject structure. So level two or three projects go under project/briefs. +4:524 minutes, 52 secondsAnd you can see separately we've got feedback project structure.md which is a specific bit of feedback that only needs to be loaded in when Claude understands +5:005 minutesthat we're looking at project structures table of contents of different bits of feedback that you've given it over time or it's understood from the way that you +5:085 minutes, 8 secondswork. Hence this file here on a specific project basis. And to demonstrate this further, I'll go to an empty folder. And you'll see that there's no memory. MD +5:175 minutes, 17 secondsfile or claude.md file inside that. So if I run the /memory command and I hit autoopen memory folder, then you can see +5:255 minutes, 25 secondsthat because it's done on a project level basis. There's no memory consolidation there. So you don't actually have to create that memory.md +5:325 minutes, 32 secondsfile. It's just quietly taking notes on your tasks and on your feedback in the background. And then it's created all those files as an index for me. So +5:395 minutes, 39 secondsclaude.md and memory. IMD is what Claude has today. And it's also very clear that Anthropic is trying to tackle this problem themselves. And that's evident +5:475 minutes, 47 secondsbecause when the Claude code source accidentally leaked a couple of weeks back, people found references to a system or framework called Chyros and +5:555 minutes, 55 secondshad a look through the code. And it's an unreleased always on demon that watches your project continuously, decides what's worth remembering, and then consolidates old notes while you sleep. +6:056 minutes, 5 secondsSo it's not in any public build yet, but for sure Anthropic in the background is working on features to actually solve this context rock problem and improve +6:146 minutes, 14 secondsthe native memory system. So it's only going to get better from this point. So level one, the setup is already done for you. It's in the background. It's +6:216 minutes, 21 secondscompletely free to use. You just need to be able to actually use them properly. +6:256 minutes, 25 secondsSo you might have noticed this if you keep repeating information to Claude that you think it should already know. +6:306 minutes, 30 secondsAnd that is where level two comes in. So level two improves the reliability of feeding those memory files in at the right time as well as improves the +Chapter 3: Level 2: Forcing Reliable Memory Recall +6:386 minutes, 38 secondsin-built structure inside cla MD. I found an article by a guy called John Connelly who's taken a concept by Pavl +6:466 minutes, 46 secondsHurin a huge name in tech who wrote this on the 18th of Feb. How to give claude code memory paste this into your projects claude. MD and bearing in mind +6:556 minutes, 55 secondsthis was before it was announced that Claude had this automemory feature but what it now does is effectively build on +7:027 minutes, 2 secondsthat structure of Claude and then when we combine it with John's we've got the ability to actually inject that automatically at the start of every +7:107 minutes, 10 secondssingle session. So basically what we're doing is we're adding in to the claude.md a big prompt all about how to manage memory and the rules in managing +7:187 minutes, 18 secondsmemory too structured memory system rooted atclaude/memory. +7:227 minutes, 22 secondsWe already saw our automatic memory system inside Claude, but instead we've got a structure here. We've got memory.mmd general.mmd which stores all +7:307 minutes, 30 secondscross project facts preferences environment setups but then we've also got domainspecific knowledge where we effectively have domain/topic +7:397 minutes, 39 secondsand each topic can have its own markdown file with domain specific knowledge one file per topic and the same with tools we can have individual tools like +7:477 minutes, 47 secondsslack.md with a specific tool config workaround edge cases for that specific tool and what this basically does is +7:557 minutes, 55 secondswe're going to add this to our claw md and we're going to go into plan mode. +7:587 minutes, 58 secondsWe're effectively going to get it to set up a memory structure for our project that we then can automatically inject into every single session. Now, this +8:078 minutes, 7 secondsworks using a claude code session start hook to ensure that when you open up that new terminal or even spin-off sub aents, it automatically loads the memory +8:168 minutes, 16 secondsor the memory MD index into session files. And if you've not used a hook before, it does exactly that. It's just a little script that basically says at +8:238 minutes, 23 secondsspecific moments like session start I'm going to inject that context into claude and we're not loading in the full context. We're just loading in the +8:318 minutes, 31 secondsmemory.mmd file which is that index if you remember. And the second most exciting thing about this is the potential for sharing this between +8:388 minutes, 38 secondsteammates. So imagine if you could sync those domain files that we talked about. +8:428 minutes, 42 secondsSo we have different products and different projects between your teammates. So if somebody's working on a different project, they can save memory files to do with that context in the +8:518 minutes, 51 secondsshared folder that we all can access inside our team. And the idea is it's specific granular detail that claw code actually needs to be useful for that +8:598 minutes, 59 secondsdomain or that tool. Now let's get it set up to show you exactly how it works. +9:039 minutes, 3 secondsSo what we're going to do is go to the link that I'll leave down below in the description under level one and we're going to copy this whole markdown section for part one. So basically +9:129 minutes, 12 secondsadding this to claw.md. What it's going to do is create a global memory directory structure which you'll probably have already based on claude's auto memory. We're going to update the +9:209 minutes, 20 secondsclaude.md file. We're going to initialize project memory.mmd files. And what it's basically looking out for is when I say reorganize memory, it's going +9:289 minutes, 28 secondsto read all the memory files. Remove the duplicates and outdated entries. Merge our entries that belong together. So basically consolidating our memories, +9:369 minutes, 36 secondssplit files that cover too many topics, restore entries by date, and update the memory. MD index. So every so often we're effectively going to be +9:459 minutes, 45 secondsreorganizing our memories. But first we just need to copy this into a prompt. +9:499 minutes, 49 secondsWe're not actually putting this directly in our claude.md file. What we are doing is opening up a new terminal window inside an existing project or an empty +9:569 minutes, 56 secondsproject. I've got my Aenttos demo project here. I'm going to switch mode using shift and tab twice to put it on plan mode. And I'm going to paste in +10:0410 minutes, 4 secondsthat entire prompt. What it's going to effectively do then is plan out a structure for our memory files and what to add to our Claude. MD file based on +10:1310 minutes, 13 secondswhat already exists and based on what already exists in our memory files. And once Claude has built the plan for part one, which was the one we copied in above, we're going to switch into plan mode again and run reorganize memory. +10:2410 minutes, 24 secondsSo, we're planning out this first. We're going to build it and then we're going to run reorganize memory with a plan to basically tidy up our memory files and +10:3210 minutes, 32 secondssee what it's built out of our previous project. So super simple. We're just going to wait for that to execute, check the plan, build it, and then execute the +10:4110 minutes, 41 secondsphrase reorganize memory to actually then push through all those changes. And you can see right now it's exploring the memory system state before it comes back +10:4910 minutes, 49 secondsto us with a plan. And it's come back to us with a plan structured persistent memory management system, setting up a global structured memory system for claw code so that knowledge persists across +10:5810 minutes, 58 secondssessions and projects. So currently our root claw.md exists but is empty. Claude memory does not exist and only one of +11:0511 minutes, 5 secondsour 28 projects has a memory/memory.mmd file. So you can see this has checked all the way up the parent tree to +11:1211 minutes, 12 secondsunderstand what exists at the highest level that will be inherited downwards. +11:1711 minutes, 17 secondsAnd the current project because it's a demo has an empty memory/ directory. No memory md. So it's going to create a +11:2411 minutes, 24 secondsglobal memory directory structure with general tools domain. It's going to update our claw.md +11:3111 minutes, 31 secondswith all five sections. Memory management, global memory, repo memory, auto init, which basically autocreates memory.mmd on a session start. And it's +11:4011 minutes, 40 secondseffectively going to go through all of our files and create that memory system and structure that we can then use to +11:4711 minutes, 47 secondsactually reorganize memory and basically set up a bunch of different domain and tool files. So, we're going to yes, clear context and bypass permissions and +11:5511 minutes, 55 secondsget it to execute on that. Then after that we will set up the ability to actually auto inject using the hook so that every time we load up a session it +12:0412 minutes, 4 secondsauto injects that memory index. So it's now built all of that. So it's created the global memory structure and you can +12:1112 minutes, 11 secondsactually commandclick into any of these files and we can see sync rules between global memories and project memories the +12:1912 minutes, 19 secondsstructure of the file and it's got the general andd the tools the domains. We can also see that got a uh cross project conventions like a general MD file and it's also done project memory.mmd file. +12:3012 minutes, 30 secondsSo on a specific project basis for all the projects we've done 28 projects it's created a specific memory MD file or consolidated that for that specific +12:3912 minutes, 39 secondsproject and you saw before that I didn't have any for previous projects except for the Aentic OS in which there was one +12:4612 minutes, 46 secondsmemory file. So what we need to do do now is just run reorganize memory. We'll make sure it's on plan mode and not bypass permissions mode. And it's going +12:5412 minutes, 54 secondsto come up with a plan to reorganize the memory and therefore it will start filling these memory MD and the claude.mmd files with the relevant +13:0113 minutes, 1 secondfolder structure outlined here. So we should see the general MD start to fill out the tools and the specific domain structure and it will tell us what it's +13:1013 minutes, 10 secondsactually going to create and then it will actually start creating that. +13:1213 minutes, 12 secondsWhilst that is happening, let's take a look at step two which is actually introducing the hook. So this hook basically injects your project memory +13:2013 minutes, 20 secondsand the global memory. MD index, if you remember that just points to the right memory files before the first tool call +13:2713 minutes, 27 secondsof every session. So this means that when you spin up an agent or a sub agent, it's going to basically throw in +13:3413 minutes, 34 secondsthat index so it knows what memories it has access to. And we're just going to copy this file here. And in summary, tells it to create the settings.json +13:4213 minutes, 42 secondsJSON hook that says when it's uh pre-tool use, make sure to run the pre-toolmemory.sh +13:5013 minutes, 50 secondsfile and it's going to create the pre-toolmemory.sh file, which is just the script to effectively load in the memory files that we've just created. +13:5713 minutes, 57 secondsAnd then it's going to go and update our claude.md to say instead of reading the claude/memory/memory md at session start, it's going to auto +14:0514 minutes, 5 secondsinject it this time. So it's not relying on Claude actually reading it and taking action. It's going to auto inject it automatically because this is a hook. +14:1314 minutes, 13 secondsAnd you can see after 5 days of usage for John specifically the number of memory files had increased significantly. So up 90% and +14:2114 minutes, 21 secondssignificantly more lines but it hasn't increased the memory. MD or general MD by a huge amount because those are just +14:2914 minutes, 29 secondsindex files pointing to the correct tools, the correct domains and the correct cycle files. So, I've asked it to reorganize the memory. And this is really brilliant. I'm just reading +14:3714 minutes, 37 secondsthrough this now. It's basically looked through my Aenttos folder and said it's +14:4314 minutes, 43 secondsfound 11 or 12, sorry, empty memory files, like daily memory files. So, there's an empty template, empty +14:5114 minutes, 51 secondstemplate, two empty sessions. So, it's saying actually, we just need to delete those because what's the point in having them? It's a waste of loading them in. +14:5814 minutes, 58 secondsSome identical first run onboarding empties. A bunch of empties there. And then part of phase two, it's basically going to trim the empty sessions. Phase +15:0615 minutes, 6 secondsthree, resolve stale open threads. So it's actually read through the specific threads in our daily memories and basically going to go and find exactly +15:1315 minutes, 13 secondswhat happened after those actions were taken to make sure that they're updated. +15:1715 minutes, 17 secondsAnd you can see it does this for a few different daily memory files. And then it's going to go through and actually add some cross references to all of these different projects that we've done +15:2515 minutes, 25 secondsto make sure that they link together correctly. It's going to update our general MD with all of these different projects that we've been working on, +15:3215 minutes, 32 secondsupdate the indexes inside the memory.mmd file, and then go through a verification phase to make sure that that all happens. So, we're basically going to run yes, clear context, and bypass +15:4115 minutes, 41 secondspermissions. It's going to make all those changes for us. And from this point onwards, we have a memory system that has a clear structure at our global directory. So, all verifications pass. +15:5115 minutes, 51 secondsIt deleted the 13 files, trimmed six sessions, finished the nine open threads, added 10 cross references, +15:5915 minutes, 59 secondsthree patterns were added to general.mmd. +16:0216 minutes, 2 secondsIt has remaining daily files of 12 with meaningful content, so it's got rid of the rubbish, and it's cleared all the empty memory directories inside the +16:1016 minutes, 10 secondsclient's folders. So now we're going to run the second prompt. And again, we're going to run it on plan mode, and then we're going to execute the plan to add +16:1816 minutes, 18 secondsto the settings.json. So that injects this every time we start a new session. +16:2216 minutes, 22 secondsOkay. So it's come up with a plan. It's going to basically register the hook in settings.json, update our global memory and claw.md so that it effectively has +16:3016 minutes, 30 secondsall of this knowledge that we're building into it. And that means everything will be executed automatically when a session starts. So for a lot of you, this will be enough. +16:3916 minutes, 39 secondsBut the moment you start running this for more than a few weeks, you're going to hit a couple of problems and your files are starting to get really messy. +16:4816 minutes, 48 secondsAnd the keyword search that works for a small amount of files using this system is going to stop working as we grow and +Chapter 4: Level 3: Search by Meaning, Not Just Keywords +16:5516 minutes, 55 secondsstart to scale. So this is where level three comes in. And this is where we start to get a bit more serious about how memory is actually organized and how +17:0217 minutes, 2 secondsit is searchable. But before we move on to that, YouTube tells me that 97% of you are watching this video right now +17:1017 minutes, 10 secondshaven't subscribed to the channel. So do me a quick favor and hit the subscribe button below if you've made it this far. +17:1617 minutes, 16 secondsSo only add to level two if these two things are true. One, you've been using Claude code for more than a month and +17:2317 minutes, 23 secondsyour memory files have grown past a handful of files. And two, if you've ever typed a question to Claude where you know the answer is somewhere in your +17:3117 minutes, 31 secondsnotes, but Claude couldn't actually find it, then it might be a sign to move on to level three. So at level two, we've got Claude loading memory more reliable. +17:3917 minutes, 39 secondsBut as you start to scale this, when you're running it for real for months across multiple clients or projects, the structure eventually stops scaling. So +17:4617 minutes, 46 secondsyou end up with a giant general MD file that can't be read efficiently. And because it's summarizing key topics and not taking words verbatim, the keyword +17:5517 minutes, 55 secondssearch starts falling apart as well. So level 3 is designed to solve both. And the template for level 3 comes from an AI agent that you're probably familiar +18:0318 minutes, 3 secondswith called openclaw. So the open claw file structure is effectively from that standalone open claw agent. It's not +18:1118 minutes, 11 secondsfrom claw code but their memory design system is something that's really genuinely powerful and clean. So it's got three different layers. First you have a memory MD which is your long-term +18:2018 minutes, 20 secondsdurable facts. So things that don't change often like your preferences, your decisions, facts about your business, and these are loaded in at the start of +18:2818 minutes, 28 secondsa recession. Second, you've got your daily note files. So you've got one file per date and you can think of these as a running log. What happened today, what +18:3618 minutes, 36 secondsgot decided, what got shipped, what didn't work, and it's basically today and yesterday's notes that get loaded automatically. And older ones are going +18:4418 minutes, 44 secondsto stay on the disc, but they're not going to get loaded into context. And then third, with open claw, there's an optional thing called dreaming. So it's a background process that's going to +18:5318 minutes, 53 secondsread through your daily notes, score them, and promote the ones that keep coming up again and again into your long-term memories. Memory MD. and the +19:0019 minutesstale stuff is going to get forgotten completely so it doesn't blow your context. So you basically then have a mechanism with a proper short-term +19:0719 minutes, 7 secondsmemory deciding with the dreaming process what is actually embedded into our long-term memory and fed into claude. So it brings us to a framework +19:1619 minutes, 16 secondscalled memsarch which is actually a plugin and it basically ports that framework from open core over to claw code. So it's built by a company called +19:2419 minutes, 24 secondszillus and that's a team behind one of the most popular open-source vector databases out there. So they know a thing or two about searching by +19:3219 minutes, 32 secondssemantics and searching by meaning and that's exactly what this is designed to do. So they've extracted open claw's memory architecture into a standalone +19:4019 minutes, 40 secondslibrary that plugs straight into claw code with a twoline install. So it's got all the benefits of the openclaw method which is the markdown first philosophy. +19:4719 minutes, 47 secondsSo everything we can go we can see we can read through and we can port it to different systems. It's got the same chunking strategy as open claw, the same +19:5519 minutes, 55 secondsfile structure with the memory.mmd and the daily notes, but now it works inside claw code too. And the way it works is it basically chunks your documents, +20:0320 minutes, 3 secondseverything you write into semantic vectors so that when we are actually searching for information, it's understanding the meaning behind our +20:1120 minutes, 11 secondsquestions and the meaning behind the stuff we've stored rather than just using keyword search. But it takes that one level further and applies a concept we've already seen already, which is +20:2020 minutes, 20 secondsactually hooks. So it auto injects the top matches into every single prompt. So as soon as we write a prompt, it's going to use a hook called user prompt submit +20:2920 minutes, 29 secondsand it's going to feed in our top three semantic matches from our memory files directly into the context for claw code. +20:3720 minutes, 37 secondsSo you don't have to remember to ask cla to search it. It's going to inject the most relevant parts of your memory files into the context pretty quickly as soon +20:4620 minutes, 46 secondsas you're actually typing in a query. So if you want to install this, we just need to take these two lines here. I'm going to go and open up a new folder and +20:5420 minutes, 54 secondsopen up cl code. And I'm just going to use the /plugin marketplace. Add zillastte mem search. It's going to find the repository and clone the repository. +21:0421 minutes, 4 secondsAnd we're going to choose to add this to our local folder so that we're not adding it above all the other memory systems that we're considering today. +21:1021 minutes, 10 secondsAnd then I'll grab the second line, plugin install memarch, and I'm going to install for you in this repo only like we just mentioned. And you can see it's +21:1821 minutes, 18 secondsspun up a settings.local.json file enabled plugins inside there and mem search plugins is true inside there. So +21:2621 minutes, 26 secondsyou need to run / reload plugins and that will help activate it. And we'll also just c twice and then reopen claw +21:3421 minutes, 34 secondscode. And then to actually verify it's working there's some GitHub instructions which I'll leave down below. We basically need to have a few conversations. So have a few +21:4121 minutes, 41 secondsconversations with it and then check your memory files. So to check your memory files, you just need to basically use the ls command inside a terminal, which is going to list whatever we're +21:5021 minutes, 50 secondsasking it to list. So mem search/memory files, and you should see today's date inside a memory file. So go ahead, have +21:5821 minutes, 58 secondsa conversation and then list and verify that that's working correctly. Or you can actually use the built-in skill that installs and that is uh memory recall. +22:0722 minutes, 7 secondsSo you can see me search, search and recall relevant memories from past sessions via mem search. So you can run that even as a slash command if you wanted to, but obviously we've got no +22:1522 minutes, 15 secondsdaily memory files yet. It will start from this point as we start building out conversations. And you can see it's using the hook user prompt submit and +22:2222 minutes, 22 secondsit's searching through the mem search files now. And this system is super similar to what we're actually using in our own Aentic OS to keep those daily +22:2922 minutes, 29 secondslog files as well as that long-term memory file that we can actually semantically push into the context at the right time. Now, there's another +22:3622 minutes, 36 secondsalternative worth knowing about, but in my opinion, not really as suitable for us called Claude MEEN. And it's a claude code plugin that automatically captures everything Claude does during your +22:4522 minutes, 45 secondscoding session, compresses it with AI, injects relevant context back into future sessions. So, sounds almost exactly the same, super popular, has a similar goal, but a different +22:5422 minutes, 54 secondsphilosophy. So, this uses MCP tools and a three tier storage model. So, it stores summaries, timeline, and +23:0123 minutes, 1 secondobservations. And it has more features than me search out the box. like it's got a little dashboard to actually search through the memories if you want. +23:0823 minutes, 8 secondsIt's got team collaboration features, cost tracking, privacy labels, but in my opinion, it's a bit overkill for what we actually need. So, if you want that +23:1623 minutes, 16 secondsmanagement layer on top of your memory, then claude mem might be able to give you that. But for our use case, it's MCP based, which means Claude has to +23:2323 minutes, 23 secondsactively decide to call the search tool rather than just injecting it from a local database like me search. And the other major difference between claude mem and mems search is claude mem is +23:3223 minutes, 32 secondsactually going to store everything in the background whereas mems search is going to keep everything in plain markdown so you can actually go back and read it. So you've got auto injections +23:4023 minutes, 40 secondseverything in readable markdown and open clause great memory patterns without actually having to leave claw code. Now level four is where we get serious with +Chapter 5: Level 4: Recall Verbatim Conversations +23:4823 minutes, 48 secondsconversation recall. So word for word recall using a service called me palace or a framework called me palace. So, you +23:5623 minutes, 56 secondsonly need to go to this level if you catch yourself thinking, I know we discussed this a few weeks ago, but I can't remember exactly what was decided. +24:0224 minutes, 2 secondsSo, where level three finds our notes and a summary of those notes, level four is designed to find exactly the words that were used when you made a decision. +24:1224 minutes, 12 secondsAnd the best part about it is it's all stored locally on your system. So, compared to the other levels so far, this is a proper RAG system. It's free +24:2224 minutes, 22 secondsand right now it's got the highest benchmark score of any memory system ever published apparently. So because it stores words verbatim, nothing ever gets +24:3124 minutes, 31 secondssummarized. So nothing can actually theoretically get lost. So here are a few snippets from the website. You can see the content stays verbatim always. +24:3924 minutes, 39 secondsThe index above it is written in a a k a dense symbolic dialect and LLM can scan at a glance. So it's written in +24:4624 minutes, 46 secondseffectively a different language. And this is what it looks like. It's got a bunch of pointers that are pointing to locations of specific data. So you +24:5524 minutes, 55 secondseffectively are searching an index which is pointing to a specific area or draw as they call it inside the second +25:0225 minutes, 2 secondsdatabase and therefore it's able to go and retrieve that information straight away. So they've got an example here. My son's name is Noah. He turns six on +25:0925 minutes, 9 secondsSeptember the 12th. So this is what you'd say into the LLM. He loves dinosaurs, etc., etc. And the pointer is +25:1625 minutes, 16 secondsthen indexed as okay, Noah, son, age six, date of birth. And it stores a bunch of information in that drawer that +25:2425 minutes, 24 secondscan then basically point it directly to draw 007 inside wing 42 room 11. And +25:3125 minutes, 31 secondswe'll come to the importance of that structure in a second. But we can basically pull information out directly as it is stored. So when we are +25:3825 minutes, 38 secondssemantically searching for information, it basically uses this memory palace which is an ancient method of memory to +25:4625 minutes, 46 secondsstore things in wings, rooms, closets and drawers. And we just saw exactly that. The pointer of a wing represents people's projects and topics. The rooms +25:5425 minutes, 54 secondscould be days, sessions or threads. The closets could be topics, threads or bundles. And then inside that is the verbatim text. So it's got a series of +26:0226 minutes, 2 secondsnested bits of information that points it to the exact correct place. And that's how it's able to actually retrieve information or store +26:0926 minutes, 9 secondsinformation. And because it's stored in that symbolic index, the AA language, it lets the model scan thousands of draws +26:1726 minutes, 17 secondsin a single pass. And it happens super quickly. So you can see an example up here without me palace and with meal. So with me palace, it basically as soon as +26:2526 minutes, 25 secondsyou say something, it's going to go and file it in a specific draw. So wing room draw. Two weeks later when you ask it a question, you're going to see it's going +26:3326 minutes, 33 secondsto retrieve in such a quick time 42 milliseconds from that exact draw and it can even pull the verbatim text to. Now +26:4126 minutes, 41 secondsthis effectively uses two separate databases. An SQL database that tracks entities and relationships between them and a Chroma DB or a Chroma vector +26:5026 minutes, 50 secondsdatabase that stores every single conversation as searchable chunks as we've seen in the drawers. And similar to some of the previous levels, it's +26:5826 minutes, 58 secondsalso using background hooks to silently store and index information. So filing and indexing happen silently through +27:0527 minutes, 5 secondsclaw code hooks on session end. So we've seen the session start hook on session end on pre-ompaction. So if you're about to compact, it will also fire the hook. +27:1427 minutes, 14 secondsYou write it and the palace is going to basically put that information somewhere behind the curtain. Now it's super easy to install. You're basically building +27:2127 minutes, 21 secondsyour palace. One command to install. So, you're going to run the commands listed down here. I'll link down in the description below to the me palaceofficial.com. But you're going to +27:3027 minutes, 30 secondsbasically install it, initialize it, and it's going to create a palace structure, wings, rooms, drawers in a me palace +27:3727 minutes, 37 secondsfolder. It's going to register all the hooks in your settings.json file, and then it's going to start working. And you can even retrospectively mine your +27:4527 minutes, 45 secondsprevious information, your previous sessions by using this mine function. So at this level then with me palace Claude can literally search every single +27:5427 minutes, 54 secondsconversation you've ever had in plain English word for word because it's all going to be indexed in that memory palace file structure in the background. +28:0228 minutes, 2 secondsNow one of the downsides here is we don't have that verbatim in markdown. So it's not exactly readable directly but we can retrieve information easily and +28:1128 minutes, 11 secondsquickly in that way. But even now everything's still locked to your local machine. Everything we talked about so far most of it is locked on your local +28:1828 minutes, 18 secondsmachine. But what about the research you did in chat GPT 3 or 4 months ago, the brainstorming you did on your phone? So that's where level five and six come in. +28:2628 minutes, 26 secondsAnd they're totally different because it's not about remembering conversations anymore. It's about how do we actually have conversations across multiple tools +28:3528 minutes, 35 secondsand also reliably store research that connects all of our different information. So everything sits in an isolated drawer in this instance and +28:4328 minutes, 43 secondsactually none of the knowledge is connected. So let's move on to level five. So at this level for the me palace, Claude can literally search every single conversation you've ever +Chapter 6: Level 5: Build a Self-Organizing Knowledge Base +28:5128 minutes, 51 secondshad in plain English word for word because it's all index in your memory palace. But even now up to this point, everything's still locked into your +29:0029 minutesmachine. So what about the research you did in chatbt last year, the brainstorm you did on your phone the other day? That's where level five and six come in. +29:0829 minutes, 8 secondsAnd they're totally different. They're not about remembering conversations anymore. It's about building up a knowledge base across tools. So level +29:1629 minutes, 16 secondsfive is totally different actually. It's not anymore about remembering conversations. The me palace is kind of +29:2429 minutes, 24 secondsthe best the pinnacle of remembering word for word conversations. So now it's about actually if you want to build a +29:3029 minutes, 30 secondsknowledge base of interconnected information. So you want to add level five if you regularly consume +29:3929 minutes, 39 secondsinformation that you want to keep and connect over time. So think about articles, videos, podcasts, client notes, anywhere where you're actually +29:4729 minutes, 47 secondsjust reading a lot of information and losing track of what you actually learned. You can connect that all into a interconnected knowledge base. So it's +29:5529 minutes, 55 secondsless about one-off projects and more about building that second brain on topics that you actually care about. But to be honest, I'd skip this if you +30:0330 minutes, 3 secondsconsume content casually and don't need to come back to it later. The most popular library out there for this you might have seen already. It's Andre +30:1030 minutes, 10 secondsCarpathy's GitHub repo called LLM wiki or his markdown file which talks about the idea of LLM wikis and it's received +30:1830 minutes, 18 secondsa huge amount of coverage. So what makes it a bit different is that it's a pattern for using claude to build a living wiki about any topic that you +30:2630 minutes, 26 secondscare about. So you literally just create two folders inside your project. You create a raw folder where you drop your source documents which your articles, +30:3330 minutes, 33 secondsyour reports, your podcast transcripts, YouTube video transcripts, PDFs and Claude is going to read from this folder but never actually write to this folder. +30:4130 minutes, 41 secondsAnd then you have a wiki folder which Claude owns completely. So it's going to write every file, maintain the structure, update cross references as +30:4930 minutes, 49 secondsyou go and you never actually write yourself to the wiki. And the whole thing again is in just plain markdown files. So we don't have an external +30:5630 minutes, 56 secondsdatabase or a vector database. It's all in readable markdown files again. And all you effectively need are the files +31:0431 minutes, 4 secondsthat we've spoken about Obsidian and an AI. And effectively inside Obsidian, which is a separate software that you +31:1231 minutes, 12 secondscan download for free. Once you compile all of your resources, you'll get this knowledge graph of how your different resources interconnect. And you've +31:2031 minutes, 20 secondsprobably seen a ton of other people demonstrating this on videos. I'm not going to do a video specifically dedicated to this method because actually I don't think it's super +31:2731 minutes, 27 secondsrelevant for how we want to synthesize information and I think Donnelly in this article summarized it quite well. It's best in use cases where you have a +31:3531 minutes, 35 secondsfolder called save for later which is basically a pile of bookmarked Slack threads, YouTube videos, client notes that you never go back to that you want +31:4331 minutes, 43 secondsto see the interlinking relationships with and as it sounds effectively create a Wikipedia on a specific subject topic. +31:5131 minutes, 51 secondsSo this is if you want to do deep research on interconnected topics. But in my opinion, I can't see the directly applicable use cases for retrieving this +31:5931 minutes, 59 secondsinformation in this manner inside a system like the business OS or the Aentic OS. If you disagree with me, I'd love to hear why in the comments below. Maybe I've missed the point of this one. +32:0832 minutes, 8 secondsI can see some use cases like actually opening up wikis for specific key topic areas you're researching in and actually having those visualized and +32:1632 minutes, 16 secondsinterconnected. But in the way that we're using it for business use cases to build out projects, I'm not sure it's the best way to utilize a memory system +32:2432 minutes, 24 secondsapart from just doing deep research on a specific topic. I've also had a few people actually surface a similar alternative called recall because it's +32:3232 minutes, 32 secondsbeen blowing up online. So recall is a hosted service that's basically Karpathy's wiki, the LLM wiki done for +32:3932 minutes, 39 secondsyou. So you install a browser extension, you can save articles, you can save all your podcasts, PDFs, etc. and Recall +32:4632 minutes, 46 secondssummarizes, tags, and auto builds that knowledge graph for you without the the setup headache, but to be honest, it's quite easy to set up the LLM wiki for +32:5432 minutes, 54 secondsyourself. There's plenty of tutorials out there that can show you how. And Recall seems to give you its own AI chat interface, so you can actually go and chat to your saved content, so it works +33:0333 minutes, 3 secondson your phone. And they also have MCP access, so you can directly connect it to claw code. And this in some ways is better than LLM Wiki because there's +33:1033 minutes, 10 secondszero setup. You don't need to configure or download Obsidian and it's basically just available through a login and all the work is obviously done for you too. +33:1833 minutes, 18 secondsWhy I think it's not as good as Carpathy's pattern for most people. The first one is ownership. So you don't actually own the data. Recall lets you export everything to markdown if you +33:2733 minutes, 27 secondswant to. But while it's live, it's actually live on their servers. So you're effectively renting and not owning your own information. And secondly, Recall seems to be built for +33:3633 minutes, 36 secondscontent consumption, not operational memory. So, it would be really good for a use case like I've watched 40 YouTube +33:4333 minutes, 43 secondsvideos on blog code. Uh, which one talked about memory and what did they mention about memory? But it's not necessarily designed for what did we +33:5133 minutes, 51 secondsdecide about client X's landing page and the conversion rates back in March. And then thirdly, because it is a off-the-shelf software, there is a +33:5833 minutes, 58 secondspricing implication too with that. So, my take is if you're non-technical and you mainly want to organize articles, videos, and podcasts, then recall is +34:0634 minutes, 6 secondsgreat. But if you want maximum control and you still want to build out that Wikipedia, then the LLM wiki will definitely beat you there. There's also +34:1434 minutes, 14 secondsa quick mention for a heavyweight alternative which is similar like knowledge graph style called light rag. +34:1934 minutes, 19 secondsSo light rag is an enterprisegrade knowledge graph and it's designed for heavier entity extraction dual level retrieval the full research grade thing +34:2834 minutes, 28 secondsbasically but it's completely overkill for 99% of business owners. You don't need the setup headache. You don't need the massive database in the background +34:3634 minutes, 36 secondsfor that and you're better off either going back to level four or if you're looking for a visual knowledge base then you can install carpathies or use recall but to be clear I think both of these +34:4534 minutes, 45 secondsare for building knowledge bases not for operational memory and therefore it probably wouldn't be used in many of our own use cases apart from research so at +34:5334 minutes, 53 secondsthis point we've covered a huge amount and well done if you stuck with it so far but also up until this point everything lives inside core code and +35:0135 minutes, 1 secondsome of you may actually not just use core code you might use chatbt on your phone, you might use cursor. And when you start using multiple AI tools, none of them know anything about each other. +35:1035 minutes, 10 secondsSo everything we've installed so far has been inside CL code. But level six is a method I've seen called open brain by Nate Jones, who has brilliant knowledge +Chapter 7: Level 6: A Single Brain For ALL Your AI Tools +35:1835 minutes, 18 secondsin this space. And the intent of this is to actually allow you to switch between AI tools constantly like chat on your +35:2635 minutes, 26 secondsphone, claw code at your desk, and it's the only system today where all of your different AIs that you're using are able to see the same memory automatically in +35:3335 minutes, 33 secondsreal time. So arguably it's the most futurep proof and most portable because actually your memory for this is going to live in a Postgress database that you +35:4035 minutes, 40 secondsown. So when the next big AI tool drops in 6 months, say you just connect it to your existing Postgress brain and +35:4835 minutes, 48 secondsthere's no actual migration needed. But if you're still living mostly in Cycl code on one machine, then it's probably worth skipping this part. So it is what +35:5635 minutes, 56 secondsit says on the tin. It's an infrastructure layer for your thinking. +36:0036 minutesSo it's one database, one chat channel, and any AI you use can plug into it, which makes it super powerful if you +36:0736 minutes, 7 secondswork across apps. You're not connected to any SAS and it's super cheap to run. +36:1136 minutes, 11 secondsI think it's less than a dollar a month to run this. So it runs on a Postgress database hosted on Superbase and inside that database there's basically one +36:2036 minutes, 20 secondstable called thoughts and every row is a single memory. So it's a chunk of text an embedding vector to be able to search for it and some tags and an associated +36:2936 minutes, 29 secondstime stamp when it was said and then it uses in-built extensions that handle all that semantic search for you. So we basically have an MCP server running +36:3736 minutes, 37 secondsfrom claw code that connects up to superbas's edge functions that act as a front door for every ai tool that wants +36:4436 minutes, 44 secondsto read from the database. So if that's sounding a little bit complicated it's because one of the downsides of this it does have an AI assisted setup but it is +36:5236 minutes, 52 secondsgoing to take significantly longer to set up than some of these others and significantly longer to understand versus others here. So, you have a full +37:0037 minutessetup guide, which I'll link down below, or a video walkthrough on YouTube from Nate himself, as well as some companion prompts that help you migrate your +37:0837 minutes, 8 secondsmemories from existing Claw Code memory systems over to this open brain. And the idea is super simple and follows a lot +37:1637 minutes, 16 secondsof what we've seen so far. For retrieval, Claude Code is going to directly query it and chat is also able to query it. Claude Desktop is able to query it. Cursor is able to query it. +37:2637 minutes, 26 secondsThey all use just the same brain effectively. And I'm not going to set this one up live as it is probably overkill for most people, but I'll link to Nate's guide which is written for +37:3537 minutes, 35 secondsnontechnical people and you'll get through it if you want to do the setup in about 30 to 45 minutes. Now, there is a live community about this. So, I +37:4237 minutes, 42 secondsrecommend having a look in the GitHub and actually joining that community if you're interested in hearing more or getting some help with the setup there. +37:4937 minutes, 49 secondsBut if you're somebody that wants to actually keep your memory portable and not associated with just claw code, then this is probably the right solution for +37:5637 minutes, 56 secondsyou. Now, there is an alternative that I quickly wanted to mention here called Mem0ero. And it's another cross tool memory layer. It's wellunded. It's +38:0438 minutes, 4 secondsreally well marketed and widely used already by developers. And you can see like used by 100,000 developers from all +38:1138 minutes, 11 secondsof these large companies. So, if you wanted something that's more production ready strength, then definitely check out mem.ai. Especially because the setup +38:1938 minutes, 19 secondsis designed to actually just get you started in less than a minute and you still have a universal self-improving AI memory layer for your LLM applications and it's completely cross tool as well. +38:2938 minutes, 29 secondsSo if you're actually shipping an AI product for example, then this might be a sensible choice for you. But again, one of the downsides here is that your data is going to live on their servers +38:3838 minutes, 38 secondspermanently. Whereas something like open brain, you actually own the superbase project and you can export the whole Postgress database whenever you want and +38:4638 minutes, 46 secondscontrol access to multiple different tools. So in terms of level six versus all the different levels, this is probably the most complex to set up. Not +38:5438 minutes, 54 secondsmem, but open brain. And it's the only one really that's going to introduce significant costs per month. Although Open Brain, as we mentioned, is going to +39:0139 minutes, 1 secondbe like 10 to 30 p per month on the free tier of Superbase. But one of the downsides compared to the other levels we've seen one we're still storing away +39:0939 minutes, 9 secondsfrom our laptop. So it's not locally held data. It is secure in a database but it effectively means we have to query an external facing database every +39:1839 minutes, 18 secondssingle time which is going to add some latency to our process. But that might be the compromise you're willing to make if you want every single AI tool you use +39:2639 minutes, 26 secondsto share that same memory for you. So I know that has been a ton of different information. So I wanted to just touch on how do you just get started today and +39:3439 minutes, 34 secondswhich one should you pick. So if you are literally just starting then don't worry about these memory systems. Turn on level one by just utilizing your +39:4239 minutes, 42 secondsclaude.md and your memory.mmd files in the right way. It's going to take you 10 minutes and it's going to be a massive improvement on the inbuilt memory +39:5039 minutes, 50 secondsinside. If you've been using claude code for a little bit then you can go to level two install John's hook and then honestly most of you should stop right +39:5839 minutes, 58 secondsthere. But if you started to build up significant amount of context and you're losing old decisions across months of work, then you can either go to level +40:0640 minutes, 6 secondsthree and install mem search or level four where we're actually verbatim word for word retrieving information from me palace. Level five and six kind of took +40:1540 minutes, 15 secondsus into a completely different realm for specific use cases. Level five was Karpathy's LLM wiki, which is best if you want to do some deep research on a +40:2340 minutes, 23 secondsspecific topic and reference the relationship between the subtopics in that topic. And then level six was all about actually if you want something that you own that's still relatively +40:3140 minutes, 31 secondscheap but you can plug into any external AI tool or LLM in the future then you want to go with something like open brain or mem. And the best part about +40:3940 minutes, 39 secondsall the things that we covered today is a lot of them do stack together. So you can run levels 1 2 and three together with no issues and actually the folder +40:4740 minutes, 47 secondsstructure is fairly sim similar and you can ask claw code to actually integrate those yourself. And in terms of what I am personally implementing, I'm +40:5540 minutes, 55 secondsimplementing up to level three inside the agentic operating system. So following those open claw conventions, but also adding on the semantic search +41:0341 minutes, 3 secondscapability and the hooks that enable actually injection of certain context at a certain time and that just improves the search and recall functionality +41:1241 minutes, 12 secondsinside the business operating system. So if you want to see more about exactly how to build out your own agentic operating system, then watch the next video. Thanks for watching. didn't see you in the next one.