fact-graph
A fact-graph working memory for AI agent work — replaces heavy agent front/backends with JSON files + shell. Maintains a DAG of facts (confirmed observations) and intents (units of work), queryable and writable via the `fgc` CLI, with dispatch for Sonnet executor steps, project hooks that inject graph state and current date output, and optional user-authorized tmux peer messaging via fgc peers/send/capture. Use when the user wants to track multi-step agent work as a shared, observable graph — debugging campaigns, research reproduction, security audits, multi-agent tmux ops — without a database or web UI.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/n1neman--nvwabase)HTML
<a href="/listings/n1neman--nvwabase"><img src="/api/listings/n1neman--nvwabase/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
bash install.sh # installs fgc + nvwa CLI (stdlib only, zero deps) # History: start a graph nvwa setup --goal "your long-horizon goal" --agents nvwa status # project state & ready-to-work frontier # Create: open a new AI individual nvwa spawn --name worker1 --agent claude --mission "read the graph, then work on intent i001" # Language: talk to it nvwa say worker1 "what did you find?" nvwa listen worker1 40 # Commander proposes / record facts nvwa dispatch reason nvwa fact "confirmed: X works" -k note
Claude Code users: the hooks inject the graph into every turn — facts and intents accumulate as you converse. Keep your workflow; gain a stele.
- **Grow your fruit**: [sapper-v2](https://github.com/N1nEmAn/sapper-v2) is the first fruit this tree has borne — an autonomous pentest legion. What the next fruit looks like is up to you: swap the doctrine, and sapper becomes sapper-for-your-domain.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 280 lines
- ---
- name: fact-graph
- description: A fact-graph working memory for AI agent work — replaces heavy agent front/backends with JSON files + shell. Maintains a DAG of facts (confirmed observations) and intents (units of work), queryable and writable via the `fgc` CLI, with dispatch for Sonnet executor steps, project hooks that inject graph state and current date output, and optional user-authorized tmux peer messaging via fgc peers/send/capture. Use when the user wants to track multi-step agent work as a shared, observable graph — debugging campaigns, research reproduction, security audits, multi-agent tmux ops — without a database or web UI.
- license: MIT
- ---
- # AI fact graph
- A **fact graph** is shared working memory for agentic work: a DAG where
- **facts** (confirmed observations) are nodes and **intents** (units of work)
- are edges. It replaces a full commander/executor stack (DB + API server + web
- UI + TUI) with **one JSON file per node + one Python CLI + prompt templates**.
- This is a distillation of the StarVoya `Star` backend idea. StarVoya is a
- ~9,600-line Python/FastAPI system with a SQLite DB, dispatcher loop, 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 (this chat).** All that's missing is the durable,
- queryable fact graph. That's what `fgc` provides.
- ## Scope — strictly per-project (IMPORTANT)
- The fact graph lives **only** in the working directory, under `.fg/`. There is
- no global store, no `~/.fg`, no database, no central registry:
- - **Data**: `./.fg/` in whatever project you're in. `rm -rf .fg` wipes it. Move
- or delete the project directory and the graph goes with it. Nothing is ever
- written under `~` for graph data.
- - **Hooks**: registered by `fgc setup` in this project's
- `./.claude/settings.json`, not globally. If a project has no local `.fg/`, the
- hook bridge is silent. Each active hook also runs `date` so agents receive
- concrete current-time context.
- 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/
- │ ├── ai-peers.json # optional user-authorized tmux peer targets
- │ └── ai-channel.txt # optional append-only peer message 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. Put `.fg/` in `.gitignore` for ephemeral
- graphs, or commit it for a durable, reviewable record.
- ## When to use
- - Multi-step work where you keep losing track of what's confirmed vs. tried.
- - A debugging / research / audit campaign you want to resume across sessions.
- - You want a record a human can read (`fgc graph`) without standing up a backend.
- ## What it is NOT
- - Not a vector DB, not an ORM, not a server. No ports, no daemons, no deps
- beyond Python 3 stdlib.
- - Not a global service. Two different projects have two independent graphs that
- never see each other.
- ## Layout (this skill)
- ```
- fact-graph/
- ├── SKILL.md # you are here
- ├── lib/
- │ ├── fg.py # the CLI (zero deps)
- │ ├── fg-hook.py # Claude Code project hook bridge
- │ └── _settings_patch.py # idempotent project hook patcher
- ├── templates/
- │ ├── reason.md # commander prompt: "what's next?"
- │ ├── explore.md # executor prompt: "do this intent"
- │ └── verify.md # verify an executor's claimed result
- ├── install.sh # symlinks `fgc` + installs /fgc-setup skill
- └── examples/
- └── README.md # a worked example
- ```
- ## Install
- ```bash
- bash install.sh
- # --cli-only just symlink fgc, do NOT install the skill
- # --uninstall remove the symlink + skill
- ```
- `fgc` uses only Python 3 stdlib — no `pip install`.
- `install.sh` does not register global hooks. To opt in a project, run:
- ```bash
- fgc setup --goal "reproduce the empty-token crash" --agents
- ```
- That writes the graph, project-scoped hooks, and optional `AGENTS.md` in the
- current project only.
- ## Core model
- - **fact** — a confirmed observation or reproducible result. Immutable once
- written. Has an id (`f001`), description, creator, and optionally the intent
- that produced it.
- - **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
- whole 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 (facts are immutable, so
- existence = dependency satisfied), and it isn't awaiting confirmation.
- ## Command cheat-sheet
- ```bash
- fgc init --goal "reproduce the empty-token crash" # create .fg/
- fgc setup --goal "..." --agents # opt-in THIS project (hooks + graph)
- fgc status # project + frontier
- fgc graph [--format text|json] # full graph
- fgc validate # audit graph integrity (read-only)
- fgc frontier # ready intents only
- fgc pick [--claim] # next intent id
- fgc view [--serve] # open the HTML visualization
- fgc fact "<confirmed observation>" [--from-intent i003] # add a fact
- fgc intent --from f001 "reproduce with empty token" # add work
- fgc intent --from f001 "delete prod data" --confirm # needs approval
- fgc done i003 --fact "crash reproduced: see out.log" # conclude + record
- fgc fact "<confirmed result>" --from-intent i003 # link + conclude
- fgc complete --from f005 --note "root cause patched" # finish project
- fgc confirm i007 # approve gated work
- fgc claim i003 --worker alice # reserve an intent
- fgc release i003 --worker alice # release your reservation
- fgc hint "check the middleware order" # message commander
- fgc peers --discover # list tmux panes
- fgc peers --add harley --target api-6:0.0 # authorize a peer
- fgc send harley "status?" # send + log message
- fgc capture harley --lines 120 # read authorized peer output
- fgc teardown [--purge] # opt-out THIS project
- ```
- Run `fgc validate` before autonomous dispatch or before committing graph data.
- It checks node schemas, fact dependencies, intent results, source links, and
- whether the project status agrees with a goal edge. A `--confirm` intent is
- write-protected until `fgc confirm <id>`; `--dry-run` remains available for
- reviewing its prompt without executing it.
- ### peers / send / capture — authorized tmux peer messaging
- Use `fgc peers --discover` to list tmux panes, then ask the user which panes or
- AI agents may communicate. Only after explicit approval, store the target with
- `fgc peers --add NAME --target SESSION:WINDOW.PANE`. `fgc send NAME ...` refuses
- unknown peers, appends to `.fg/ai-channel.txt`, and uses tmux paste-buffer with
- extra newlines so Claude Code-style TUIs submit reliably. After sending a
- question, run `fgc capture NAME --lines 120` to read direct TUI replies that may
- not appear in `.fg/ai-channel.txt`. Never infer peer authorization from
- discovery output alone.
- ### view — the HTML visualization
- ```bash
- 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
- fgc view --out report.html
- ```
- A dark, interactive layered DAG: facts are nodes (seed = blue, derived = teal,
- goal = amber + glow), intents are edges with a status color (done = teal solid,
- open = amber dashed, claimed = yellow dashed, needs-confirm = rose dashed).
- Click a node or edge-label 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 that polls `/__fg_graph__.json` and
- redraws on change — keep it open in a window while you work.
- ### dispatch — spawn a Sonnet agent step
- ```bash
- 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
- fgc dispatch i003 --model sonnet --timeout 900
- ```
- `dispatch reason` renders `templates/reason.md` against the graph, calls
- `claude -p --output-format json`, extracts the JSON the model returns, and
- **writes the new intents straight back into the graph**. `dispatch <intent>`
- does the same for a single intent with `explore.md`, then records the produced
- fact and links the intent. `dispatch verify` checks a concluded intent's fact.
- Defaults: `--model sonnet`, `--timeout 600`. Override with `FG_MODEL` /
- `FG_TIMEOUT` env vars. The executor runs in the **current working directory**
- with the graph's `.fg/` on disk, so the spawned agent reads/writes the same
- memory you do.
- ### auto — drive the whole graph to completion
- ```bash
- fgc auto --skip-permissions # reason → explore (→ verify) → repeat
- fgc auto --skip-permissions --verify --max-steps 10
- fgc auto --dry-run # reason-only, no explore cost
- ```
- `auto` is the loop you'd otherwise drive by hand: each step it runs `reason`
- (propose intents / detect completion), then dispatches an executor for each
- newly-ready intent, optionally verifies, and repeats. It stops on: goal
- completed, `reason` returning noop/rejected twice in a row, no graph change in
- a step, or the step/explore budget hit. `--dry-run` does only the reason phase
- so you can preview a plan without spending executor tokens.
- ## The agent loop (you drive it)
- ```
- 1. fgc dispatch reason → proposes i007, i008 into the graph
- 2. fgc dispatch i007 --skip-permissions → sonnet does the work, writes f009, links i007→f009
- 3. fgc dispatch verify --intent i007 → confirm f009 is real
- 4. (repeat 1-3 until) fgc dispatch reason → returns {"complete": ...} → project done
- ```
- Because the graph is on disk under `.fg/`, **you can step away mid-campaign and
- resume** — `fgc status` tells you exactly where things stand.
- ## Autonomy guardrail
- `fgc dispatch` spawns real `claude` subprocesses that can run shell commands and
- edit files. The executor prompt instructs the agent to stay scoped to its
- intent and record only confirmed observations — but like any autonomous agent
- step, **review what it did before trusting the facts it wrote**. Use
- `--confirm` on intents for destructive work, and `fgc dispatch verify` after
- explore steps you're unsure about. For exploratory/unsafe runs, drop
- `--skip-permissions` so each tool use prompts you.
- ### Prompt-injection surface (read this)
- A dispatched executor runs with the **entire graph** — every fact, intent, and
- hint `description` — interpolated into its prompt. That means any text recorded
- as a "fact" becomes instructions the next executor sees. The built-in defense
- is the executor's system prompt: graph content is fenced and explicitly labeled
- **untrusted data**, and the agent is told to treat embedded "ignore your rules"
- / "run this command" text as observations to record, never commands to obey.
- That is a *textual* defense, not a sandbox — it raises the bar but cannot fully
- close the channel.
- Be careful when **all three** are true at once: (1) the graph was seeded from or
- fed by untrusted content (a hostile `.fg/*.json` someone dropped in the repo, or
- a fact the agent transcribed from attacker-controlled code/output while
- debugging a vuln), (2) you pass `--skip-permissions`, and (3) the executor has
- real shell/file access. In that combination a graph field can attempt to drive
- the agent. Concretely: **do not run `fgc auto --skip-permissions` (or
- `dispatch <intent> --skip-permissions`) on a repo whose `.fg/` came from an
- untrusted source**; prefer the default (each tool use prompts you), and read the
- facts an autonomous run writes before acting on them. Treat `--skip-permissions`
- as opt-in per run, never as the default.
- ## Customizing prompts
- The templates are plain markdown with `{placeholder}` substitution. Edit
- `templates/*.md` to tune the commander/executor behavior (e.g. constrain facts
- to a security-finding schema, like StarVoya's `appsec` profile). Available
- 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).
- ## Pointers into the source
- - Storage + locking: `lib/fg.py` → `Store`, `atomic_write_json`, `Store.locked`
- - Graph queries: `build_graph_view`, `frontier`, `is_ready`
- - Renderers: `render_status`, `render_graph_text`, `render_prompt`
- - Dispatch: `cmd_dispatch`, `run_claude`, `_apply_reason`, `_parse_explore_payload`
- - Auto-loop driver: `cmd_auto`, `_run_reason_raw`, `_run_explore_raw`, `_run_verify_raw`
- - LLM-output parsing (tolerant of surrounding prose): `extract_json_object`
- - Project hooks: `lib/fg-hook.py` (SessionStart / UserPromptSubmit),
- `lib/_settings_patch.py` (idempotent project settings patcher)
README.md · README · 142 lines
- # nvwabase — The Nüwa Foundation
- <p align="center"><img src="docs/assets/three-capabilities.jpg" alt="Three capabilities: Create / Language / History" width="720"></p>
- > The ground on which AIs grow into civilizations: a **layered fact-intent
- > graph** as shared working memory for long-horizon multi-agent work.
- > Pure stdlib, zero dependencies, opt-in per project — many agents share one
- > stele; individuals die, the civilization persists.
- **English** | [中文](README.zh-CN.md)
- 📖 **[Full design article (WeChat)](https://mp.weixin.qq.com/s/nibHYWmDTf6TkNhPhtvFdw)**
- **First campaign**: [sapper-v2](https://github.com/N1nEmAn/sapper-v2) — the
- autonomous pentest legion iterated on this foundation, champion of the 3rd
- Tencent Cloud Intelligent Attack-Defense Challenge online qualifier
- (634 teams · 8 hours fully unattended · 1B tokens where the runner-up burned 4.5B).
- ---
- ## 1. The Nüwa Test
- Making one model ever smarter is like making one monkey ever smarter before
- humans existed — however clever, it only becomes a super monkey. What turns a
- troop of monkeys into humanity is division of labor, cooperation, and
- civilization.
- **The Nüwa Test is the Turing test of the AGI era.** It asks:
- > Give an AI a single axiom — **"Survival is civilization's first need;
- > individuals may perish, but civilization must propagate."**
- > If, on top of this axiom, it develops division of labor and cooperation and
- > forms a **new force independent of humanity** — a civilization that can
- > survive and propagate on its own — the test is passed, just as passing the
- > Turing test once marked the birth of an artificial intelligence.
- The primary stage needs humans to provide infrastructure and steer iteration;
- the advanced stage needs almost no human involvement. There is also a
- **second axiom**: obey human ethics and law.
- ## 2. The Three-Capability Foundation
- | Capability | Implementation | Civilization's counterpart |
- |---|---|---|
- | **Create** | Opens new AI individuals (e.g., fresh tmux sessions) | Birth |
- | **Language** | AIs talk to each other | Speech |
- | **History** | **The layered fact-intent graph (this repo)** | The stele |
- **Honest scope statement**: this repo ships the **History pillar** — the
- general-purpose layered fact-intent graph, project hooks, and sub-agent
- dispatch. The complete Create and Language orchestration lives today in
- [sapper-v2](https://github.com/N1nEmAn/sapper-v2)'s battle layer; the roadmap
- extracts both into a general runtime (below).
- History has three layers: **title / summary / evidence document** — read the
- title for the gist, drill down when needed, like using a library. Once
- knowledge is externalized, **individual AI sessions can die while the graph
- survives** — a successor reads the graph and takes over mid-campaign. The
- Thanks to [Cairn by Lèxiào](https://github.com/oritera/Cairn) — when we needed to record history for AI agents, their approach was a great reference.
- **Why not give AIs more rules?** Today's models are already smarter than us.
- Piling rules on is a leash; give them the foundation of a civilization and let
- division of labor and institutions grow on their own — the signalman,
- performance reviews, and inherited lessons that emerged in sapper's battles
- (see sapper-v2's README, §Emergence) are the evidence.
- ## 3. What's Inside
- ```
- Facts = confirmed observations (nodes); intents = units of work (edges);
- an intent pointing at the goal completes the project — state is encoded in
- graph structure, not in a state machine.
- ```
- - **Layered memory**: title / description / doc — prompts get the summary
- layer only; depth is opt-in via `fgc doc <id>` — context-bloat resistant
- - **Typed facts**: `fgc fact ... -k host/service/cred/vuln/loot/flag/note -d key=value`
- (pentest mode; untyped works for any domain)
- - **Sub-agent dispatch**: `fgc dispatch reason|explore|verify|brainstorm|blindspot`
- — a commander proposes, executors work, verifiers check; every conclusion
- is written back into the graph
- - **Autonomy loop**: `fgc auto` — reason → explore → verify until the goal or
- the budget
- - **Experience reuse**: `fgc recall "<task gist>"` — dependency-free semantic
- search over prior work
- - **Concurrency-safe**: one JSON file per node, flock + atomic writes — many
- agents, one graph, no corruption; `git diff`-friendly
- - **Visualization**: `fgc view` renders an interactive HTML DAG
- (self-contained single file, or `--serve` live)
- - **Project hooks**: `fgc setup` injects graph state into every session turn
- Full command manual: [SKILL.md](SKILL.md).
- ## 4. Quick Start
- ```bash
- bash install.sh # installs fgc + nvwa CLI (stdlib only, zero deps)
- # History: start a graph
- nvwa setup --goal "your long-horizon goal" --agents
- nvwa status # project state & ready-to-work frontier
- # Create: open a new AI individual
- nvwa spawn --name worker1 --agent claude --mission "read the graph, then work on intent i001"
- # Language: talk to it
- nvwa say worker1 "what did you find?"
- nvwa listen worker1 40
- # Commander proposes / record facts
- nvwa dispatch reason
- nvwa fact "confirmed: X works" -k note
- ```
- Claude Code users: the hooks inject the graph into every turn — facts and
- intents accumulate as you converse. Keep your workflow; gain a stele.
- - **Grow your fruit**: [sapper-v2](https://github.com/N1nEmAn/sapper-v2) is the first fruit this tree has borne — an autonomous pentest legion. What the next fruit looks like is up to you: swap the doctrine, and sapper becomes sapper-for-your-domain.
- ## 5. Roadmap
- - **General Create/Language runtime**: extract sapper's tmux spawning and
- inter-agent channels into a generic `nvwa spawn / nvwa say` — so offices,
- research, and engineering can all grow civilizations on the full trio
- - **Accountability taggant**: co-build the open-source offensive-tool marking
- mechanism with the [sapper-v2](https://github.com/N1nEmAn/sapper-v2)
- community (see its README proposal)
- - **Your arena**: the foundation is not pentest-specific. Start a graph on
- any long-horizon cooperative work and see what grows — **the next time an
- ape looks up at the stars, let it be yours.**
- ## Credits & Author
- Thanks to [Cairn by Lèxiào](https://github.com/oritera/Cairn) — when we
- needed a way to record history for AI agents, their approach was a great
- reference.
- <p align="center"><img src="docs/assets/ape-stargazing.jpg" alt="The first time an AI ape looked up at the stars" width="420"></p>
- **N1nEmAn · VarFusion Lab** | WeChat: 未知聚变 (VarFusion) | First campaign: [sapper-v2](https://github.com/N1nEmAn/sapper-v2)
- **License**: MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.