convez.ai
AgenteAutomaçãoIntermediário
N1nEmAn

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 GitHub
InicialPluginScore · de 0 a 100

Um 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-graph

1 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

Estrelas
71
Forks
37
Acompanhando
1
Saúde
42%
Último commit
há 1 semana
Versão
—
Issues abertas
0
Contribuidores
1

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 reason proposes next work; dispatch <intent> does it; dispatch verify checks it.
  • Observable, resumable process — fgc graph / fgc view show exactly where things stand; close the terminal and resume tomorrow.
  • Autonomous, but you drive it — fgc auto runs 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 (null while open). An intent whose to == "goal" completes the project.
  • hint — a live human message to the commander.
  • goal — a special terminal fact created at init time.

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.flock is not available on Windows.
  • The claude CLI on PATH for dispatch / 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

Ver o original no GitHub

Bom para

Relacionados