Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
docs: document ix savings, its flags, and its llm records (#577)
KageBinarye2524d27fe5f
diff --git a/docs/llm-format.md b/docs/llm-format.mdindex 68ed1501..99bf1bb5 100644--- a/docs/llm-format.md+++ b/docs/llm-format.md@@ -171,6 +171,28 @@ of two field sets it is holding. `saved_at` is on it because the `context`record that follows says whether the snapshot was fresh when it was taken, notwhen that was.+`ix savings --detail`:++```+savings model="Claude Opus ($15/MTok in, $75/MTok out)"+scope name=session commands=726 tokens_saved=832739 naive_tokens=1099164 actual_tokens=266425 money_saved=27.48 water_saved_ml=1665.478+command scope=session name=callers count=329 tokens_saved=334995+scope name=lifetime commands=4820 tokens_saved=6142880 naive_tokens=8003104 actual_tokens=1860224 money_saved=202.72 water_saved_ml=12285.76+command scope=lifetime name=callers count=2104 tokens_saved=2210488+```++(Truncated: one `command` record is shown per scope, and a real run emits one+per entry in that scope's breakdown.)++The two `scope` records are always emitted; `command` records appear only under+`--detail` and carry their own `scope=` because both scopes are broken down in+one stream. They are emitted inside the scope loop, so they follow their own+`scope` record rather than being grouped at the end — a parser reading the+stream in order sees session's breakdown before the lifetime `scope` line.++`money_saved` is the only field `--model` moves — the token and water figures+are model-independent.+Error line:```diff --git a/skills/ix/references/commands.md b/skills/ix/references/commands.mdindex c7160357..989c0ffe 100644--- a/skills/ix/references/commands.md+++ b/skills/ix/references/commands.md@@ -65,6 +65,55 @@ These aggregate multiple graph operations into single bounded responses.| Start backend | `ix docker start` | `ix docker start` || Graph statistics | `ix stats` | `ix stats --format json` |+## Session Metrics++| Goal | Command | Example |+|---|---|---|+| Token savings so far | `ix savings` | `ix savings --format llm` |+| Per-command breakdown | `ix savings --detail` | `ix savings --detail --format llm` |+| Clear lifetime totals | `ix savings reset` | `ix savings reset` |++`ix savings` reports how many tokens the graph saved against a naive+read-the-files baseline, in two scopes. Neither is per-terminal: the CLI sends a+bare `GET /v1/savings` with no session id, so the backend has nothing to+attribute a count to one shell with. `session` is an in-memory counter the+backend process has accumulated since it started, **shared by every client that+talks to it**; `lifetime` is the persisted total. So a fresh shell against a+backend that has been up all day reads that day's traffic from every other+shell as its "session". Each scope carries the command count, `tokens_saved`,+the `naive_tokens` / `actual_tokens` it was derived from, and money and water+estimates.++| Flag | Value | Default | Effect |+|---|---|---|---|+| `--detail` | — | off | Add one record per command type, within each scope |+| `--model <model>` | `opus\|sonnet\|haiku\|gpt-4o` | `opus` | Pricing table for `money_saved` only — token and water figures do not change |+| `--format <fmt>` | `text\|json\|llm` | `text` | See output-formats.md |++`ix savings reset` clears **both** scopes (`DELETE /v1/savings`, which runs+`session.set(empty) *> store.resetSavings`). It takes no flags, does not prompt,+and cannot be undone — there is no way to zero one scope and keep the other,+despite the CLI's own "Reset lifetime savings totals" description.++`--format llm` emits one `savings` header record and one `scope` record per+scope; `--detail` adds `command` records that name their scope:++```+savings model="Claude Opus ($15/MTok in, $75/MTok out)"+scope name=session commands=726 tokens_saved=832739 naive_tokens=1099164 actual_tokens=266425 money_saved=27.48 water_saved_ml=1665.478+command scope=session name=callers count=329 tokens_saved=334995+command scope=session name=entity count=308 tokens_saved=423741+scope name=lifetime commands=4820 tokens_saved=6142880 naive_tokens=8003104 actual_tokens=1860224 money_saved=202.72 water_saved_ml=12285.76+command scope=lifetime name=callers count=2104 tokens_saved=2210488+```++`command` records are emitted inside the scope loop, so each scope's breakdown+follows its own `scope` record rather than being grouped at the end. (Truncated+above: a real run emits one `command` record per entry in each breakdown.)++Reading a graph command's savings needs the backend up: the numbers come from+`GET /v1/savings`, not from a local file.+## Decomposition Recipes**"How does ingestion work?"**