caveman vs graphify: two ways to handle your docs

Part of the reduce Claude Code token usage pillar. Both of these tools have something to say about documentation, and they say completely different things.

Is caveman or graphify the better choice?

graphify if your project's knowledge lives in documents the agent keeps re-reading; caveman if the document you keep re-sending is your own memory file. That is the sharpest way to separate them, and it is not how either one is usually described. graphify maps the whole project — code, documentation, PDFs, images, video — into a queryable graph. caveman compresses the model's speech, and separately rewrites CLAUDE.md into telegraphic form. Neither shows a measurable session-cost saving on my open long-session benchmark. I run it and sell a competing tool, so read the mechanism rather than the placing.

What does graphify actually do?

It builds a knowledge graph the agent queries instead of grepping files. Python, MIT, installed from PyPI, invoked as a /graphify slash command across Claude Code, Codex, opencode, Cursor, Copilot, Aider, OpenClaw and others. Its differentiator is coverage. Most tools in this category index source and stop. graphify also ingests documentation, PDFs, images and video — which matters in projects where the answer to "why is it built this way" lives in a design document or a recorded walkthrough rather than in a function body. It also produces a persistent, inspectable artefact: graph.json, plus an HTML view and a Markdown report. The graph is queryable later without re-reading the codebase, and a human can audit the HTML view rather than trusting the index blind. The costs: indexing is an explicit step you must re-run as the project moves, a stale graph misleads quietly rather than failing loudly, it does not touch command output, and it needs a Python runtime where single-binary alternatives do not.

What does caveman actually do?

Three things, and only one of them is the famous one. The famous one is the speaking style: a JavaScript skill or plugin for 30-plus agents that switches output to telegraphic "caveman talk" at four levels — lite, full, ultra, wenyan — with an honest benchmark behind it: 65% average output reduction, range 22–87%, measured on raw Claude API receipts against an already-concise baseline. The other two are input-side:

caveman-compress rewrites CLAUDE.md and memory files into telegraphic form, around 46% input savings. This is the one that belongs on this page: your memory file is re-sent on every single turn, so a permanent 46% cut there compounds across the whole session in a way nothing else in caveman does.
caveman-shrink wraps any MCP server and compresses its tool descriptions — another standing per-turn cost.

The stated trade-off: style enforcement can degrade reasoning quality on nuanced explanations. That applies to the speaking style, not to the two rewriters.

Two opposite theories of documentation

graphify's theory: the docs contain answers, so make them queryable. Rather than the agent reading a 40-page specification to find one constraint, it queries a graph built from that specification once. caveman's theory: one document is sent every turn, so make it shorter. CLAUDE.md is not read on demand — it is prefix, resent with every message. Forty per cent off a file paid once per turn is a different kind of saving from forty per cent off a file read occasionally. Both theories are correct about their own object. The practical consequence is that they do not substitute for each other at all: caveman-compress does nothing about your PDFs, and graphify does nothing about your memory file. There is one caution worth stating. CLAUDE.md is part of the cached prompt prefix on providers that support prompt caching, and cached input is billed at a fraction of fresh input. Rewriting it once is a permanent win. Rewriting it repeatedly invalidates the cache each time, which can cost more than the 46% saves. Compress it, then leave it alone.

What does neither of them do?

Command output. graphify is not on that path; caveman governs model speech, not tool results.
Whole-file reads for editing. A graph says which file; nothing here shrinks the file the agent then opens.
Re-reads. The same file entering context four times costs four times. Neither deduplicates.
Conversation history. Neither compresses the window as it grows.

Where does each one leave money on the table?

graphify leaves the memory file and the tool manifests. Both are prefix: sent on every turn regardless of what the session does. A graph reduces occasional reads and does nothing about the fixed cost paid before your first message. caveman leaves everything the agent reads. File contents, command output, search results — the style governs what the model says, not what it is given. caveman-shrink is the exception and it covers exactly one category: MCP tool descriptions. Put together, the pair covers speech, memory file and tool manifests on one side, and occasional document reads on the other. What falls between them is the largest thing in most sessions: the files the agent opens to work on, opened in full, sometimes more than once. That gap is not a criticism of either project. It is the reason two tools with honest published numbers can both leave a session costing what it cost before.

Which one should you pick?

Pick graphify if your project's knowledge is not all in the source — architecture documents, specifications, vendor PDFs, recorded handovers. Nothing else in this category ingests those, and that is a genuine gap it fills. Pick caveman if your work is output-heavy, or specifically for caveman-compress and caveman-shrink. Those two apply to almost everyone and neither carries the style's quality trade-off. Pick both if you have a document-heavy project and a long CLAUDE.md. They do not conflict and they cover different documents. Pick neither yet if you have not measured. One week with ccusage gives you the input/output ratio that decides the style question outright.

How to apply this today

Run caveman-compress on your memory file once, then leave it alone. Permanent per-turn saving, no quality trade-off, no repeated cache invalidation.
Ask whether your project's knowledge is in the source. If yes, graphify's non-code ingestion buys you nothing.
Tie graph re-indexing to an event, not to memory — a branch switch, a daily run. A stale graph is worse than none.
Get your input/output ratio before enabling the speaking style.

What goes wrong (anti-patterns)

Re-running caveman-compress on a schedule. Each rewrite invalidates the cached prefix. Once is the right number. Installing a graph you never query. The indexing cost is real; the payoff is zero if the agent never asks. Trusting a stale index. Confident wrong answers cost more than no answer. Enabling ultra on work you need to understand. The readme warns about degraded nuanced reasoning.

See also: