Speculator

Stop paying tokens to find your own code.

Speculator gives Claude a persistent memory of your architecture — stored as a knowledge graph right in your repo.

---

The problem

Every time Claude needs to understand your codebase, it reads dozens of files — burning your budget before writing a single line.

	Without Speculator	With Speculator
Files read per task	~40 files	0 files
Knows "why"?	Never	Always
Finds related code?	Maybe	Instantly
Tokens per task	~12 000	~800

---

Install

macOS / Linux — 60 seconds:

curl -fsSL https://github.com/madlexa/speculator/releases/latest/download/install.cmd | bash

Windows (CMD or PowerShell):

curl -fsSL https://github.com/madlexa/speculator/releases/latest/download/install.cmd -o install.cmd && install.cmd

One command bootstraps everything:

• downloads tools/speculator.cmd — no global install needed
• wires hooks into .claude/settings.json — Claude queries your graph automatically
• writes AGENTS.md with the knowledge-graph protocol
• creates knowledge/ directory ready for entities and edges

Manual install

# Step 1 — download CLI wrapper
curl -fsSL https://github.com/madlexa/speculator/releases/latest/download/speculator.cmd \
     -o tools/speculator.cmd
chmod +x tools/speculator.cmd

# Step 2 — configure hooks, AGENTS.md, settings.json
bash tools/speculator.cmd setup

# Step 3 — initialize the knowledge base
bash tools/speculator.cmd init knowledge

---

How it works

1. Document

Add entities and edges to the graph using the CLI or MCP. Store architecture decisions, reasons, and relationships — right in your repo.

$ speculator add entity "auth" "JWT auth middleware"
$ speculator add edge auth user-service uses

2. Query

Claude asks the graph instead of reading files. One call returns the entity, all its edges, and the reasons behind every decision.

$ speculator get auth --facet reason
→ compliance requirement, added 2026-03

$ speculator list edges --from auth
→ user-service, jwt-utils, session-store

3. Act

Claude makes precise changes — knowing what's connected, why it was built that way, and what will break. No guessing, no rereading.

✓ why auth exists
✓ what depends on it
✓ safe to change

---

Entities and edges

Entity — any named concept that non-engineers use as a noun: Order, PaymentGateway, NotificationTemplate. Not every class deserves an entity — utilities and helpers live as sections inside the entity that owns them.

Edge A → B — a documented dependency. Typed sections:

Section	Content
## Human	WHY this dependency exists — the decision, constraint, or history
## Code	WHERE — file:line, class, method, call chain in order
## Db	Table, fields, SQL/ORM contract
## Rest	HTTP method, path, key params
## Queue	Topic, message schema, ordering guarantees
## Cache	Key pattern, TTL, invalidation

---

CLI reference

bash tools/speculator.cmd search "keywords"
bash tools/speculator.cmd get entity-slug
bash tools/speculator.cmd get from-slug to-slug
bash tools/speculator.cmd get entity-slug --facet Human
bash tools/speculator.cmd get entity-slug --depth 2
bash tools/speculator.cmd list entities
bash tools/speculator.cmd list edges
bash tools/speculator.cmd add entity "Name" "summary for search"
bash tools/speculator.cmd add edge from-slug to-slug relation
bash tools/speculator.cmd update from-slug to-slug Code "file:line — method"
bash tools/speculator.cmd stats
bash tools/speculator.cmd validate

---

Agent compatibility

Agent	Mechanism	Notes
Claude Code	AGENTS.md + .claude/ hooks	Automatic context injection on every prompt
Codex CLI	AGENTS.md	Protocol loaded at session start
Cursor / Windsurf / other	AGENTS.md	Protocol loaded at session start

---

MCP server

For direct integration with Claude Code, add to .mcp.json:

{
  "mcpServers": {
    "speculator": {
      "command": "node",
      "args": [
        "dist/mcp.js",
        "--dir",
        "knowledge"
      ]
    }
  }
}

Run bash tools/speculator.cmd setup first — it prompts the agent to build dist/mcp.js if needed.

---

Updating

rm -rf .tools/speculator
bash tools/speculator.cmd list entities

---

Requirements

• Node.js 20+
• jq (for Claude Code hooks)
• curl (for initial download)