A self-organizing,
Git-backed knowledge base.

Write path

1. POST /content validates, appends a job to .knowledged/queue.json (atomic rename), returns 202.
2. The single worker picks the oldest queued job and flips it to processing on disk before any work begins.
3. Organizer calls the LLM with INDEX.md + content, parses a strict-JSON decision, applies refactors, writes the file and updated index.
4. Store makes one atomic git commit: store(<jobID>): path.

Read path

• ?path=… — direct file read, no LLM.
• ?query=…&mode=raw — LLM picks ≤5 relevant paths from INDEX.md, server reads them.
• ?query=… — same relevance call, then a synthesis call that answers from those files only.
• ?tag=… / ?tags=a,b&match=all — derived from a cached tag index rebuilt from frontmatter on staleness.

Crash recovery

On startup the queue scans queue.json. processing jobs are resolved against git log: if a commit contains the job ID, the job is marked done; otherwise it is reset to queued and retried. Commits are atomic — exact-once semantics fall out of git.

Repository layout

<repo>/
├── .gitignore         # ignores /.knowledged/
├── .knowledged/
│   ├── queue.json     # live job queue
│   └── origin-push.json
├── INDEX.md           # auto-maintained
└── <topic>/<sub>/<file>.md

Concurrency model

HTTP GET handlers read the filesystem directly with no locking. POST handlers acquire the queue mutex only to persist the job and signal the worker. The worker goroutine is the single writer of git — no concurrent git writes are possible by construction.

LLM provider interface

type Provider interface {
  Complete(ctx, system, user, opts…) (string, error)
  CompleteStructured(ctx, system, user, schema, opts…) (string, error)
}

One method per provider. The only call option today is WithReasoningBudget(n), forwarded to POST /ask when a non-zero --ask-reasoning-budget is set.