Knowledge Genome System

A pipeline that turns raw notes into a compounding, reviewable knowledge base — and, from that knowledge, into working code.

Notes land in Obsidian. Syncthing carries them to the storage server, where a quiet-window watcher commits them. A webhook wakes a GPU node, a local model reads the source and writes wiki pages, deterministic scripts validate the result, and a pull request opens for a human to accept or reject. Nothing enters the knowledge base without that gate.

Layer three does the same for code: it reads the intention in a note, and when a decision is ratified it produces unit tests first, then — once you approve the tests — the implementation, each as its own pull request.

Obsidian ──▶ Syncthing ──▶ storage-node ──▶ Forgejo ──▶ n8n ──▶ ai-node (GPU)
                                                            │
                                       wiki PR ◀────────────┤
                                                            │
                                  spec PR ──▶ [gate] ──▶ impl PR

---

Documentation

Core Philosophy	Why raw is immutable and the wiki is derived
Architecture	Repository structure, the three layers, linked projects
Installation	System requirements, prerequisites, per-OS setup
Configuration	globals.env, registry.sh, tokens
Quick Start	First run, Makefile reference
Testing	The bats suite and what each file covers
Genome Lifecycle	Creating, linking, retiring a genome
Security Model	Trust boundaries, git-crypt, key management
Agent Sessions	How the model is driven, and what it may not do
Workflows	n8n flows, storage-node watcher, ai-node wrapper
Knowledge Schema	Page types, frontmatter, linking rules
Intent & Code Generation	Layer three: intention, spec-first, project repos
Collaboration Model	Working with the system as a team
Optional Extensions	Cross-genome pulls, power management
Troubleshooting	When something goes wrong
Runbook	The manual acts: keys, genomes, releases, tokens
Pipeline test	One pass of six notes through every stage of the system
What the test found	The register that pass produced, open and closed

Templates live in templates/ and are the single source of truth for the PR description and the wiki log format — read them there rather than from a copy in the docs.

The manifests in meta/ describe this repository to its own tooling: every environment variable, the workflow graph, the pipeline's verbs and locks, and the map of what is specific to one installation. They are inputs, not documentation — make abstraction and the bats suite check the tree against them, so a manifest that drifts is a failure rather than a stale page.

---

Quick start

git clone <this-repo> && cd knowledge-genome-orchestrator
$EDITOR registry.sh                 # define your genomes
cp local.env.example local.env      # your forge URL, user, hosts
make webhook-secrets                # generate the webhook path secrets
export FORGEJO_TOKEN=...            # or use the Bitwarden helper
make deps                           # verify the toolchain
make setup                          # create repos, scaffold, push
make test                           # 587 tests, must be green

Then deploy the AI node:

scp -r . ai-node:~/knowledge-genome-orchestrator/
ssh ai-node 'cd ~/knowledge-genome-orchestrator && sudo ./deploy/ai-node/install.sh'
ssh ai-node 'cd ~/knowledge-genome-orchestrator && ./deploy/ai-node/setup-dev-env.sh'

---

The three layers

Layer	Owner	Artifact	Gate
1 — raw	you	immutable sources under raw/	none: capture is never blocked
2 — wiki	model + deterministic scripts	compiled knowledge under wiki/	pull request on the genome
3 — project	bootstrap / spec / codegen skills	code in a linked repository	two pull requests: tests, then implementation

The rule that holds all three together is the same: the model proposes, deterministic scripts decide. Every stochastic output is validated by something testable before it is trusted, and every artifact reaches a human as a diff.

---

Design principles

Raw is append-only. Sources are never edited by a machine. Everything derived can be regenerated; the sources cannot.

The model gets no shell. Skills return structured JSON. Scripts do the file writes, the git operations, and the API calls. A stochastic process never holds a credential or a working tree.

Everything arrives as a pull request. The wiki, the tests, the implementation. Rejection is a first-class path: a review comment routes back in as guided feedback rather than a manual fix, so the skill learns and the loop closes.

Failures degrade toward doing nothing. If the intent layer breaks, the system behaves exactly as it did before that layer existed. Knowledge capture is the primary function and nothing may block it.

---

Hardware

Built to run on a small self-hosted setup: a storage server for the repositories and n8n, a GPU node behind Proxmox for the model, and a laptop that only ever holds Obsidian. Anything with a 16 GB card runs the local model comfortably; see Installation for the tested configuration.