Skip to content
Back to search

fact-graph

SkillWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/n1neman--nvwabase/badge.svg)](/listings/n1neman--nvwabase)

HTML

<a href="/listings/n1neman--nvwabase"><img src="/api/listings/n1neman--nvwabase/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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
  1. ---
  2. name: fact-graph
  3. 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.
  4. license: MIT
  5. ---
  6. # AI fact graph
  7. A **fact graph** is shared working memory for agentic work: a DAG where
  8. **facts** (confirmed observations) are nodes and **intents** (units of work)
  9. are edges. It replaces a full commander/executor stack (DB + API server + web
  10. UI + TUI) with **one JSON file per node + one Python CLI + prompt templates**.
  11. This is a distillation of the StarVoya `Star` backend idea. StarVoya is a
  12. ~9,600-line Python/FastAPI system with a SQLite DB, dispatcher loop, container
  13. runtime, and a TypeScript TUI. Most of that weight exists to run *outside*
  14. Claude Code. **Inside Claude Code you already have the executor (Claude), the
  15. scheduler (you), and the UI (this chat).** All that's missing is the durable,
  16. queryable fact graph. That's what `fgc` provides.
  17. ## Scope — strictly per-project (IMPORTANT)
  18. The fact graph lives **only** in the working directory, under `.fg/`. There is
  19. no global store, no `~/.fg`, no database, no central registry:
  20. - **Data**: `./.fg/` in whatever project you're in. `rm -rf .fg` wipes it. Move
  21. or delete the project directory and the graph goes with it. Nothing is ever
  22. written under `~` for graph data.
  23. - **Hooks**: registered by `fgc setup` in this project's
  24. `./.claude/settings.json`, not globally. If a project has no local `.fg/`, the
  25. hook bridge is silent. Each active hook also runs `date` so agents receive
  26. concrete current-time context.
  27. A project that uses the graph:
  28. ```
  29. your-project/
  30. ├── .fg/ # ALL graph data lives here, nowhere else
  31. │ ├── project.json # origin, goal, status, id counters
  32. │ ├── facts/{goal,f001,…}.json
  33. │ ├── intents/i001.json …
  34. │ ├── hints/
  35. │ ├── ai-peers.json # optional user-authorized tmux peer targets
  36. │ └── ai-channel.txt # optional append-only peer message log
  37. └── AGENTS.md # (optional) protocol for dispatched agents
  38. ```
  39. One file per node makes the graph `git diff`-able. Writes are atomic
  40. (`os.replace`) and guarded by `fcntl.flock`, so multiple agents can touch the
  41. graph concurrently without corruption. Put `.fg/` in `.gitignore` for ephemeral
  42. graphs, or commit it for a durable, reviewable record.
  43. ## When to use
  44. - Multi-step work where you keep losing track of what's confirmed vs. tried.
  45. - A debugging / research / audit campaign you want to resume across sessions.
  46. - You want a record a human can read (`fgc graph`) without standing up a backend.
  47. ## What it is NOT
  48. - Not a vector DB, not an ORM, not a server. No ports, no daemons, no deps
  49. beyond Python 3 stdlib.
  50. - Not a global service. Two different projects have two independent graphs that
  51. never see each other.
  52. ## Layout (this skill)
  53. ```
  54. fact-graph/
  55. ├── SKILL.md # you are here
  56. ├── lib/
  57. │ ├── fg.py # the CLI (zero deps)
  58. │ ├── fg-hook.py # Claude Code project hook bridge
  59. │ └── _settings_patch.py # idempotent project hook patcher
  60. ├── templates/
  61. │ ├── reason.md # commander prompt: "what's next?"
  62. │ ├── explore.md # executor prompt: "do this intent"
  63. │ └── verify.md # verify an executor's claimed result
  64. ├── install.sh # symlinks `fgc` + installs /fgc-setup skill
  65. └── examples/
  66. └── README.md # a worked example
  67. ```
  68. ## Install
  69. ```bash
  70. bash install.sh
  71. # --cli-only just symlink fgc, do NOT install the skill
  72. # --uninstall remove the symlink + skill
  73. ```
  74. `fgc` uses only Python 3 stdlib — no `pip install`.
  75. `install.sh` does not register global hooks. To opt in a project, run:
  76. ```bash
  77. fgc setup --goal "reproduce the empty-token crash" --agents
  78. ```
  79. That writes the graph, project-scoped hooks, and optional `AGENTS.md` in the
  80. current project only.
  81. ## Core model
  82. - **fact** — a confirmed observation or reproducible result. Immutable once
  83. written. Has an id (`f001`), description, creator, and optionally the intent
  84. that produced it.
  85. - **intent** — a unit of work. `from` = facts it depends on; `to` = the fact it
  86. produced (`null` while open). An intent whose `to == "goal"` completes the
  87. whole project.
  88. - **hint** — a live human message to the commander.
  89. - **goal** — a special terminal fact created at `init` time.
  90. State is **encoded in graph structure**, not a state field: an intent is
  91. "ready" iff it's open, its `from` facts all exist (facts are immutable, so
  92. existence = dependency satisfied), and it isn't awaiting confirmation.
  93. ## Command cheat-sheet
  94. ```bash
  95. fgc init --goal "reproduce the empty-token crash" # create .fg/
  96. fgc setup --goal "..." --agents # opt-in THIS project (hooks + graph)
  97. fgc status # project + frontier
  98. fgc graph [--format text|json] # full graph
  99. fgc validate # audit graph integrity (read-only)
  100. fgc frontier # ready intents only
  101. fgc pick [--claim] # next intent id
  102. fgc view [--serve] # open the HTML visualization
  103. fgc fact "<confirmed observation>" [--from-intent i003] # add a fact
  104. fgc intent --from f001 "reproduce with empty token" # add work
  105. fgc intent --from f001 "delete prod data" --confirm # needs approval
  106. fgc done i003 --fact "crash reproduced: see out.log" # conclude + record
  107. fgc fact "<confirmed result>" --from-intent i003 # link + conclude
  108. fgc complete --from f005 --note "root cause patched" # finish project
  109. fgc confirm i007 # approve gated work
  110. fgc claim i003 --worker alice # reserve an intent
  111. fgc release i003 --worker alice # release your reservation
  112. fgc hint "check the middleware order" # message commander
  113. fgc peers --discover # list tmux panes
  114. fgc peers --add harley --target api-6:0.0 # authorize a peer
  115. fgc send harley "status?" # send + log message
  116. fgc capture harley --lines 120 # read authorized peer output
  117. fgc teardown [--purge] # opt-out THIS project
  118. ```
  119. Run `fgc validate` before autonomous dispatch or before committing graph data.
  120. It checks node schemas, fact dependencies, intent results, source links, and
  121. whether the project status agrees with a goal edge. A `--confirm` intent is
  122. write-protected until `fgc confirm <id>`; `--dry-run` remains available for
  123. reviewing its prompt without executing it.
  124. ### peers / send / capture — authorized tmux peer messaging
  125. Use `fgc peers --discover` to list tmux panes, then ask the user which panes or
  126. AI agents may communicate. Only after explicit approval, store the target with
  127. `fgc peers --add NAME --target SESSION:WINDOW.PANE`. `fgc send NAME ...` refuses
  128. unknown peers, appends to `.fg/ai-channel.txt`, and uses tmux paste-buffer with
  129. extra newlines so Claude Code-style TUIs submit reliably. After sending a
  130. question, run `fgc capture NAME --lines 120` to read direct TUI replies that may
  131. not appear in `.fg/ai-channel.txt`. Never infer peer authorization from
  132. discovery output alone.
  133. ### view — the HTML visualization
  134. ```bash
  135. fgc view # write a self-contained fact-graph.html snapshot + open it
  136. fgc view --serve # live page that auto-refreshes every 2s as the graph changes
  137. fgc view --out report.html
  138. ```
  139. A dark, interactive layered DAG: facts are nodes (seed = blue, derived = teal,
  140. goal = amber + glow), intents are edges with a status color (done = teal solid,
  141. open = amber dashed, claimed = yellow dashed, needs-confirm = rose dashed).
  142. Click a node or edge-label for a detail panel; drag to pan, scroll to zoom.
  143. The static snapshot inlines the JSON so it opens from `file://` with no server;
  144. `--serve` starts a stdlib HTTP server that polls `/__fg_graph__.json` and
  145. redraws on change — keep it open in a window while you work.
  146. ### dispatch — spawn a Sonnet agent step
  147. ```bash
  148. fgc dispatch reason # commander: read graph, propose next intents
  149. fgc dispatch i003 --skip-permissions # executor: work intent i003
  150. fgc dispatch verify --intent i003 # verify i003's claimed result
  151. fgc dispatch reason --dry-run # just print the rendered prompt
  152. fgc dispatch i003 --model sonnet --timeout 900
  153. ```
  154. `dispatch reason` renders `templates/reason.md` against the graph, calls
  155. `claude -p --output-format json`, extracts the JSON the model returns, and
  156. **writes the new intents straight back into the graph**. `dispatch <intent>`
  157. does the same for a single intent with `explore.md`, then records the produced
  158. fact and links the intent. `dispatch verify` checks a concluded intent's fact.
  159. Defaults: `--model sonnet`, `--timeout 600`. Override with `FG_MODEL` /
  160. `FG_TIMEOUT` env vars. The executor runs in the **current working directory**
  161. with the graph's `.fg/` on disk, so the spawned agent reads/writes the same
  162. memory you do.
  163. ### auto — drive the whole graph to completion
  164. ```bash
  165. fgc auto --skip-permissions # reason → explore (→ verify) → repeat
  166. fgc auto --skip-permissions --verify --max-steps 10
  167. fgc auto --dry-run # reason-only, no explore cost
  168. ```
  169. `auto` is the loop you'd otherwise drive by hand: each step it runs `reason`
  170. (propose intents / detect completion), then dispatches an executor for each
  171. newly-ready intent, optionally verifies, and repeats. It stops on: goal
  172. completed, `reason` returning noop/rejected twice in a row, no graph change in
  173. a step, or the step/explore budget hit. `--dry-run` does only the reason phase
  174. so you can preview a plan without spending executor tokens.
  175. ## The agent loop (you drive it)
  176. ```
  177. 1. fgc dispatch reason → proposes i007, i008 into the graph
  178. 2. fgc dispatch i007 --skip-permissions → sonnet does the work, writes f009, links i007→f009
  179. 3. fgc dispatch verify --intent i007 → confirm f009 is real
  180. 4. (repeat 1-3 until) fgc dispatch reason → returns {"complete": ...} → project done
  181. ```
  182. Because the graph is on disk under `.fg/`, **you can step away mid-campaign and
  183. resume** — `fgc status` tells you exactly where things stand.
  184. ## Autonomy guardrail
  185. `fgc dispatch` spawns real `claude` subprocesses that can run shell commands and
  186. edit files. The executor prompt instructs the agent to stay scoped to its
  187. intent and record only confirmed observations — but like any autonomous agent
  188. step, **review what it did before trusting the facts it wrote**. Use
  189. `--confirm` on intents for destructive work, and `fgc dispatch verify` after
  190. explore steps you're unsure about. For exploratory/unsafe runs, drop
  191. `--skip-permissions` so each tool use prompts you.
  192. ### Prompt-injection surface (read this)
  193. A dispatched executor runs with the **entire graph** — every fact, intent, and
  194. hint `description` — interpolated into its prompt. That means any text recorded
  195. as a "fact" becomes instructions the next executor sees. The built-in defense
  196. is the executor's system prompt: graph content is fenced and explicitly labeled
  197. **untrusted data**, and the agent is told to treat embedded "ignore your rules"
  198. / "run this command" text as observations to record, never commands to obey.
  199. That is a *textual* defense, not a sandbox — it raises the bar but cannot fully
  200. close the channel.
  201. Be careful when **all three** are true at once: (1) the graph was seeded from or
  202. fed by untrusted content (a hostile `.fg/*.json` someone dropped in the repo, or
  203. a fact the agent transcribed from attacker-controlled code/output while
  204. debugging a vuln), (2) you pass `--skip-permissions`, and (3) the executor has
  205. real shell/file access. In that combination a graph field can attempt to drive
  206. the agent. Concretely: **do not run `fgc auto --skip-permissions` (or
  207. `dispatch <intent> --skip-permissions`) on a repo whose `.fg/` came from an
  208. untrusted source**; prefer the default (each tool use prompts you), and read the
  209. facts an autonomous run writes before acting on them. Treat `--skip-permissions`
  210. as opt-in per run, never as the default.
  211. ## Customizing prompts
  212. The templates are plain markdown with `{placeholder}` substitution. Edit
  213. `templates/*.md` to tune the commander/executor behavior (e.g. constrain facts
  214. to a security-finding schema, like StarVoya's `appsec` profile). Available
  215. placeholders: `{origin}`, `{goal}`, `{graph_yaml}`, `{fact_ids}`,
  216. `{open_intents}`, `{hints}`, `{max_intents}` (reason); `{graph_yaml}`,
  217. `{intent_id}`, `{intent_description}` (explore); `{intent_description}`,
  218. `{result_description}` (verify).
  219. ## Pointers into the source
  220. - Storage + locking: `lib/fg.py` → `Store`, `atomic_write_json`, `Store.locked`
  221. - Graph queries: `build_graph_view`, `frontier`, `is_ready`
  222. - Renderers: `render_status`, `render_graph_text`, `render_prompt`
  223. - Dispatch: `cmd_dispatch`, `run_claude`, `_apply_reason`, `_parse_explore_payload`
  224. - Auto-loop driver: `cmd_auto`, `_run_reason_raw`, `_run_explore_raw`, `_run_verify_raw`
  225. - LLM-output parsing (tolerant of surrounding prose): `extract_json_object`
  226. - Project hooks: `lib/fg-hook.py` (SessionStart / UserPromptSubmit),
  227. `lib/_settings_patch.py` (idempotent project settings patcher)
README.md · README · 142 lines
  1. # nvwabase — The Nüwa Foundation
  2. <p align="center"><img src="docs/assets/three-capabilities.jpg" alt="Three capabilities: Create / Language / History" width="720"></p>
  3. > The ground on which AIs grow into civilizations: a **layered fact-intent
  4. > graph** as shared working memory for long-horizon multi-agent work.
  5. > Pure stdlib, zero dependencies, opt-in per project — many agents share one
  6. > stele; individuals die, the civilization persists.
  7. **English** | [中文](README.zh-CN.md)
  8. 📖 **[Full design article (WeChat)](https://mp.weixin.qq.com/s/nibHYWmDTf6TkNhPhtvFdw)**
  9. **First campaign**: [sapper-v2](https://github.com/N1nEmAn/sapper-v2) — the
  10. autonomous pentest legion iterated on this foundation, champion of the 3rd
  11. Tencent Cloud Intelligent Attack-Defense Challenge online qualifier
  12. (634 teams · 8 hours fully unattended · 1B tokens where the runner-up burned 4.5B).
  13. ---
  14. ## 1. The Nüwa Test
  15. Making one model ever smarter is like making one monkey ever smarter before
  16. humans existed — however clever, it only becomes a super monkey. What turns a
  17. troop of monkeys into humanity is division of labor, cooperation, and
  18. civilization.
  19. **The Nüwa Test is the Turing test of the AGI era.** It asks:
  20. > Give an AI a single axiom — **"Survival is civilization's first need;
  21. > individuals may perish, but civilization must propagate."**
  22. > If, on top of this axiom, it develops division of labor and cooperation and
  23. > forms a **new force independent of humanity** — a civilization that can
  24. > survive and propagate on its own — the test is passed, just as passing the
  25. > Turing test once marked the birth of an artificial intelligence.
  26. The primary stage needs humans to provide infrastructure and steer iteration;
  27. the advanced stage needs almost no human involvement. There is also a
  28. **second axiom**: obey human ethics and law.
  29. ## 2. The Three-Capability Foundation
  30. | Capability | Implementation | Civilization's counterpart |
  31. |---|---|---|
  32. | **Create** | Opens new AI individuals (e.g., fresh tmux sessions) | Birth |
  33. | **Language** | AIs talk to each other | Speech |
  34. | **History** | **The layered fact-intent graph (this repo)** | The stele |
  35. **Honest scope statement**: this repo ships the **History pillar** — the
  36. general-purpose layered fact-intent graph, project hooks, and sub-agent
  37. dispatch. The complete Create and Language orchestration lives today in
  38. [sapper-v2](https://github.com/N1nEmAn/sapper-v2)'s battle layer; the roadmap
  39. extracts both into a general runtime (below).
  40. History has three layers: **title / summary / evidence document** — read the
  41. title for the gist, drill down when needed, like using a library. Once
  42. knowledge is externalized, **individual AI sessions can die while the graph
  43. survives** — a successor reads the graph and takes over mid-campaign. The
  44. 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.
  45. **Why not give AIs more rules?** Today's models are already smarter than us.
  46. Piling rules on is a leash; give them the foundation of a civilization and let
  47. division of labor and institutions grow on their own — the signalman,
  48. performance reviews, and inherited lessons that emerged in sapper's battles
  49. (see sapper-v2's README, §Emergence) are the evidence.
  50. ## 3. What's Inside
  51. ```
  52. Facts = confirmed observations (nodes); intents = units of work (edges);
  53. an intent pointing at the goal completes the project — state is encoded in
  54. graph structure, not in a state machine.
  55. ```
  56. - **Layered memory**: title / description / doc — prompts get the summary
  57. layer only; depth is opt-in via `fgc doc <id>` — context-bloat resistant
  58. - **Typed facts**: `fgc fact ... -k host/service/cred/vuln/loot/flag/note -d key=value`
  59. (pentest mode; untyped works for any domain)
  60. - **Sub-agent dispatch**: `fgc dispatch reason|explore|verify|brainstorm|blindspot`
  61. — a commander proposes, executors work, verifiers check; every conclusion
  62. is written back into the graph
  63. - **Autonomy loop**: `fgc auto` — reason → explore → verify until the goal or
  64. the budget
  65. - **Experience reuse**: `fgc recall "<task gist>"` — dependency-free semantic
  66. search over prior work
  67. - **Concurrency-safe**: one JSON file per node, flock + atomic writes — many
  68. agents, one graph, no corruption; `git diff`-friendly
  69. - **Visualization**: `fgc view` renders an interactive HTML DAG
  70. (self-contained single file, or `--serve` live)
  71. - **Project hooks**: `fgc setup` injects graph state into every session turn
  72. Full command manual: [SKILL.md](SKILL.md).
  73. ## 4. Quick Start
  74. ```bash
  75. bash install.sh # installs fgc + nvwa CLI (stdlib only, zero deps)
  76. # History: start a graph
  77. nvwa setup --goal "your long-horizon goal" --agents
  78. nvwa status # project state & ready-to-work frontier
  79. # Create: open a new AI individual
  80. nvwa spawn --name worker1 --agent claude --mission "read the graph, then work on intent i001"
  81. # Language: talk to it
  82. nvwa say worker1 "what did you find?"
  83. nvwa listen worker1 40
  84. # Commander proposes / record facts
  85. nvwa dispatch reason
  86. nvwa fact "confirmed: X works" -k note
  87. ```
  88. Claude Code users: the hooks inject the graph into every turn — facts and
  89. intents accumulate as you converse. Keep your workflow; gain a stele.
  90. - **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.
  91. ## 5. Roadmap
  92. - **General Create/Language runtime**: extract sapper's tmux spawning and
  93. inter-agent channels into a generic `nvwa spawn / nvwa say` — so offices,
  94. research, and engineering can all grow civilizations on the full trio
  95. - **Accountability taggant**: co-build the open-source offensive-tool marking
  96. mechanism with the [sapper-v2](https://github.com/N1nEmAn/sapper-v2)
  97. community (see its README proposal)
  98. - **Your arena**: the foundation is not pentest-specific. Start a graph on
  99. any long-horizon cooperative work and see what grows — **the next time an
  100. ape looks up at the stars, let it be yours.**
  101. ## Credits & Author
  102. Thanks to [Cairn by Lèxiào](https://github.com/oritera/Cairn) — when we
  103. needed a way to record history for AI agents, their approach was a great
  104. reference.
  105. <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>
  106. **N1nEmAn · VarFusion Lab** | WeChat: 未知聚变 (VarFusion) | First campaign: [sapper-v2](https://github.com/N1nEmAn/sapper-v2)
  107. **License**: MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.