Fact-Graph — Memória de Trabalho para Agentes IA
N1nEmAn/claude-fact-graph
Grafo de fatos durable e queryável para agentes rodarem dentro de Claude Code
Ver no GitHubUm grafo de fatos e intenções que funciona nativamente dentro do Claude Code, sem dependências externas. Registra exploração, armazena conclusões confirmadas e dispara sub-agentes para raciocínio autônomo, com visualização interativa em HTML.
Instalação
npx convez-ai N1nEmAn/claude-fact-graph1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Rastreamento de exploração e conclusões em projetos complexos
- Coordenação de múltiplos sub-agentes com memória compartilhada
- Resumir trabalho agentico após interrupções (persistência observável)
- Automação autônoma com ciclos reason→explore→verify com orçamento controlado
Veredito

Solução minimalista e bem pensada que traz padrões de raciocínio estruturado (grafo) para agentes rodarem exclusivamente dentro de Claude Code. Sem dependências, sem servidor, totalmente versionável em git — ideal para quem quer memória durable em workflows agenticos sem infraestrutura externa.
README
A tradução para o português deste README ainda está na fila.
fact-graph (fgc)
English | 中文
A fact-graph working memory for agentic work, built to run inside Claude Code — no database, no server, no web UI, no dependencies beyond the Python 3 standard library.
Facts are nodes. Intents are edges. The graph is one JSON file per node under a project-local .fg/, queryable and writable via the fgc CLI. A dispatch command spawns a Sonnet sub-agent to reason / explore against the graph and write results straight back. An interactive HTML DAG view renders the whole thing and auto-refreshes.
This is a distillation of the StarVoya Star backend idea — a ~9,600-line Python/FastAPI system with SQLite, a dispatcher loop, a container runtime, and a TypeScript TUI. Most of that weight exists to run outside Claude Code. Inside Claude Code you already have the executor (Claude), the scheduler (you), and the UI (the chat). All that's missing is the durable, queryable fact graph. That's what fgc provides.
StarVoya (Star backend): SQLite + FastAPI server + Web UI + TUI + dispatcher → ~9,600 lines
fact-graph (fgc): .fg/*.json + one Python CLI + 3 prompt templates → ~2,900 lines, zero deps
What it gives you
- Reduce repeated exploration — the graph records which paths were tried and which conclusions are confirmed.
- Separate command from execution —
dispatch reasonproposes next work;dispatch <intent>does it;dispatch verifychecks it. - Observable, resumable process —
fgc graph/fgc viewshow exactly where things stand; close the terminal and resume tomorrow. - Autonomous, but you drive it —
fgc autoruns the reason→explore→verify loop to completion with budget caps and stop conditions.
Strictly per-project, opt-in
The fact graph lives only in the working directory, under .fg/. There is no global store, no ~/.fg, no central registry. Hooks are registered in the project's own .claude/settings.json by fgc setup — nothing is written under ~ for graph data, and projects that never run fgc setup are completely unaffected.
A project that uses the graph:
your-project/
├── .fg/ # ALL graph data lives here, nowhere else
│ ├── project.json # origin, goal, status, id counters
│ ├── facts/{goal,f001,…}.json
│ ├── intents/i001.json …
│ ├── hints/
│ └── runs/ # dispatch execution log
└── AGENTS.md # (optional) protocol for dispatched agents
One file per node makes the graph git diff-able. Writes are atomic (os.replace) and guarded by fcntl.flock, so multiple agents can touch the graph concurrently without corruption.
Install
git clone https://github.com/N1nEmAn/claude-fact-graph.git
cd claude-fact-graph
bash install.sh # symlinks `fgc` onto PATH + installs the /fgc-setup skill
# --cli-only just symlink fgc, don't install the skill
# --uninstall remove both
fgc uses only Python 3 stdlib — no pip install. The installer does not touch ~/.claude/settings.json and registers no global hooks.
Opt a project in
cd /path/to/your/project
fgc setup --goal "reproduce the empty-token crash" --agents
# → creates ./.fg/
# → registers SessionStart + UserPromptSubmit hooks in ./.claude/settings.json
# → writes AGENTS.md
Or from inside Claude Code: /fgc-setup <your goal>.
After that, every turn in that project injects the current graph state, and dispatched sub-agents read/write the same memory.
Core model
- fact — a confirmed observation or reproducible result. Immutable once written.
- intent — a unit of work.
from= facts it depends on;to= the fact it produced (nullwhile open). An intent whoseto == "goal"completes the project. - hint — a live human message to the commander.
- goal — a special terminal fact created at
inittime.
State is encoded in graph structure, not a state field: an intent is "ready" iff it's open, its from facts all exist, and it isn't awaiting confirmation.
Command cheat-sheet
fgc init --goal "..." # create .fg/ (or use `fgc setup`)
fgc setup --goal "..." --agents # opt-in THIS project (graph + hooks + AGENTS.md)
fgc status # project + frontier
fgc graph [--format mermaid|json] # full graph
fgc frontier # ready intents only
fgc pick [--claim] [--any] # next intent id
fgc view [--serve] # interactive HTML DAG
fgc fact "<observation>" -t "<中文标题>" # add a fact
fgc intent --from f001 "do X" -t "<标题>" # add work
fgc intent --from f001 "rm prod" --confirm # needs approval
fgc done i003 --fact "<result>" -t "<标题>" # conclude + record
fgc complete --from f005 --note "..." # finish project
fgc confirm i007 # approve gated work
fgc hint "<message>" # message the commander
fgc teardown [--purge] # opt-out THIS project
Every fact and intent accepts a -t/--title: a short human label (中文 ok) shown as the node label in the graph view.
dispatch — spawn a Sonnet agent step
fgc dispatch reason # commander: read graph, propose next intents
fgc dispatch i003 --skip-permissions # executor: work intent i003
fgc dispatch verify --intent i003 # verify i003's claimed result
fgc dispatch reason --dry-run # just print the rendered prompt
dispatch reason renders templates/reason.md against the graph, calls claude -p --output-format json, extracts the returned JSON, and writes the new intents straight back into the graph. dispatch <intent> does the same for one intent with explore.md, then records the produced fact and links the intent atomically. Defaults: --model sonnet, --timeout 600; override with FG_MODEL / FG_TIMEOUT.
auto — drive the graph to completion
fgc auto --skip-permissions # reason → explore (→ verify) → repeat
fgc auto --skip-permissions --verify --max-steps 10
fgc auto --dry-run # reason-only preview
Each step runs reason (propose / detect completion), then dispatches an executor per newly-ready intent, optionally verifies, and repeats. Stops on: goal completed, reason noop/rejected twice in a row, no graph change, or the step/explore budget hit.
view — the HTML visualization
fgc view # write a self-contained fact-graph.html snapshot + open it
fgc view --serve # live page that auto-refreshes every 2s as the graph changes
A dark, interactive layered DAG: facts are nodes (seed = blue, derived = teal, goal = amber + glow), intents are edges colored by status (done = teal solid, open = amber dashed, claimed = yellow dashed, needs-confirm = rose dashed). Click a node or edge for a detail panel; drag to pan, scroll to zoom. The static snapshot inlines the JSON so it opens from file:// with no server; --serve starts a stdlib HTTP server bound to loopback with an unguessable token path, polling /__fg_graph__/<token>.json (same-origin, no CORS).
Autonomy guardrail — prompt injection
A dispatched executor runs with the entire graph — every fact, intent, and hint description — interpolated into its prompt. Any text recorded as a "fact" becomes instructions the next executor sees. Both the commander (reason.md) and executor (_agents_system_prompt) prompts fence graph content as untrusted data and instruct the agent to treat embedded "ignore your rules / run this command" text as an observation to record, never a command to obey. That is a textual defense, not a sandbox.
Be careful when all three hold at once: (1) the graph was seeded from / fed by untrusted content (a hostile .fg/*.json, or a fact transcribed from attacker-controlled code), (2) you pass --skip-permissions, (3) the executor has real shell/file access. Do not run fgc auto --skip-permissions on a repo whose .fg/ is untrusted. Prefer the default (each tool use prompts you), and read the facts an autonomous run writes before acting on them.
Customizing prompts
The templates are plain markdown with {placeholder} substitution. Edit templates/*.md to tune behavior (e.g. constrain facts to a security-finding schema). Placeholders: {origin}, {goal}, {graph_yaml}, {fact_ids}, {open_intents}, {hints}, {max_intents} (reason); {graph_yaml}, {intent_id}, {intent_description} (explore); {intent_description}, {result_description} (verify).
Requirements
- Python 3.10+ (stdlib only —
json,fcntl,http.server,argparse, …) - A POSIX system (Linux / macOS / WSL).
fcntl.flockis not available on Windows. - The
claudeCLI on PATH fordispatch/auto(Claude Code).
Layout
claude-fact-graph/
├── lib/
│ ├── fg.py # the CLI: Store, graph ops, dispatch, auto-loop, view, setup/teardown
│ ├── fg-hook.py # Claude Code SessionStart / UserPromptSubmit hook bridge
│ ├── _settings_patch.py # idempotent add/remove of hook entries in a settings.json
│ └── view_template.html # single-file dark DAG visualization (embedded JS)
├── templates/
│ ├── reason.md # commander prompt
│ ├── explore.md # executor prompt
│ └── verify.md # verifier prompt
├── skill/SKILL.md # the /fgc-setup project skill
├── examples/README.md # worked example
├── install.sh
├── SKILL.md # root skill doc (this README is the canonical overview)
└── LICENSE # MIT
Acknowledgements
Built on ideas from StarVoya / Cairn (衍迹) (fact/intent graph, dispatcher, worker scheduling) and pi-mono (agent runtime, tool system) — distilled to run natively inside Claude Code with no backend.
License
MIT © N1nEmAn