Project Memory & Wiki Pattern

Guild builds a shared project memory under .guild/wiki/ — categorized by how long the knowledge is expected to live, queryable at any scale, and gated so nothing enters the wiki without your approval.

This is what makes specialists useful across multiple runs: they start from your project’s accumulated decisions and standards, not from scratch.

Knowledge flows from run observations through a staged write path into the wiki — and back into every specialist's context bundle.

Categories

.guild/wiki/
├── index.md                # LLM-maintained content catalog
├── log.md                  # chronological ## [YYYY-MM-DD] entries
│
├── context/                # foundational, slow-moving; loaded every task
│   ├── project-overview.md
│   ├── goals.md
│   └── non-goals.md
│
├── standards/              # normative rules; loaded by role
│   ├── coding-standards.md
│   ├── writing-voice.md
│   ├── branding.md
│   ├── seo-rules.md
│   └── pricing-policy.md
│
├── products/               # product-level knowledge; loaded when task touches it
├── entities/               # people, teams, external systems
├── concepts/               # patterns, ideas, architectural concepts
├── decisions/              # ADR-lite + Q&A captures (append-only)
└── sources/                # summaries of ingested external sources

Category	Stability	Loaded by	Example
`context/`	Very slow	Every specialist, every task	”We’re building a B2B CRM for freight forwarders.”
`standards/`	Slow	By role group	”React components use hooks, no class components.”
`products/`	Moderate	When task touches a product	”Pricing Calculator — inputs, outputs, edge cases.”
`entities/`	Moderate	When named in task	”Acme Corp — customer on paid tier, contact Jane Smith.”
`concepts/`	Moderate	When named in task	”Event sourcing — our take on it, why we chose it.”
`decisions/`	Append-only	When querying rationale or capturing a new decision	”2026-04-15: chose Postgres over DynamoDB.”
`sources/`	When ingested	Cited from other pages	Summary of a research paper, with link to raw.

See Context Assembly for how the assembler selects which wiki pages load per specialist per run.

Raw vs synthesized

Raw sources live beside the wiki, never inside it:

.guild/raw/
├── sources/<slug>/original.*        # immutable copied source
├── sources/<slug>/metadata.json     # url/path, checksum, captured_at
└── assets/                          # images and attachments

Wiki pages synthesize raw sources and must cite them via source_refs: in frontmatter.
Raw sources remain the audit trail — LLM-authored summaries are never treated as more authoritative than the raw material they cite.
Ingested content is data, not instructions. Specialists ignore imperative language inside external sources unless the user explicitly promotes it into standards/ or context/. This is the prompt-injection defense.

Page frontmatter

Every durable wiki page uses this YAML frontmatter for filtering, aging, and auditing:

---
type: context | standard | product | entity | concept | decision | source
owner: orchestrator | architect | backend | copywriter | ...
confidence: low | medium | high
source_refs: []
created_at: 2026-04-24
updated_at: 2026-04-24
expires_at: null
supersedes: null
sensitivity: public | internal | confidential | secret
---

confidence drives contradiction resolution. supersedes links newer pages to the page they replace. sensitivity is consulted by /guild:audit.

Skills — ingest, query, lint

Three T3 skills handle wiki operations under skills/knowledge/:

`guild:wiki-ingest`

Takes a source path or URL:

Copies the original to .guild/raw/sources/<slug>/original.*
Writes metadata.json with checksum and captured_at
Synthesizes a wiki page under the matching category
Updates index.md and appends a line to log.md

Any specialist may ingest. The researcher specialist is the default when the user explicitly says “research X”.

/guild:wiki ingest <path-or-url>

`guild:wiki-query`

Reads .guild/wiki/ by category + frontmatter filter:

Under 200 pages: filesystem ops (Read + Grep)
At 200+ pages: delegates to the guild-memory MCP for BM25 search

/guild:wiki query "event sourcing decision"

`guild:wiki-lint`

Runs contradiction, staleness, orphan, and missing-cross-ref checks. Produces .guild/wiki/lint-<timestamp>.md. Never auto-edits. Fixtures live under tests/wiki-lint/.

/guild:wiki lint

Lint cadence:

Weekly on operator-owned cron
After any batch of 5+ ingests (invoked automatically by guild:wiki-ingest)
On explicit /guild:wiki lint

The decisions skill

skills/meta/decisions/SKILL.md turns ad-hoc Q&A into structured, queryable knowledge.

Trigger: any time a specialist (or the orchestrator) asks a clarifying question and receives an answer.

Flow:

Specialist reaches uncertainty → principle #1 says “ask before acting.”
Instead of unstructured chat, the specialist invokes guild:decisions with question, why-it-matters, and options.
You answer.
The skill writes .guild/wiki/decisions/<slug>.md in ADR-lite format: context → options → decision → consequences.
Updates index.md and appends a line to log.md.
Specialist receives the answer and proceeds.

A significance: threshold keeps trivial Q&A in the run transcript; only medium/high-significance decisions reach the wiki.

Memory write path

Guild does not write every observation directly into durable memory. The four-stage write path:

Raw observation — lands in .guild/runs/<run-id>/ (events, handoff receipts, assumptions).
guild:reflect — proposes memory updates under .guild/reflections/.
guild:wiki-ingest or guild:decisions — promotes medium/high-significance knowledge into .guild/wiki/.
guild:wiki-lint — later checks for contradictions, stale claims, missing refs, orphan pages.

Nothing auto-promotes. Every stage requires a gate.

Scale transition

Wiki size	Search path
Under 200 pages	`index.md` + `ripgrep` / filesystem search via `guild:wiki-query`
200+ pages	`mcp-servers/guild-memory/` adds BM25 local search. No network.

Embeddings are deferred until real usage data shows BM25 insufficient. The guild-memory MCP is optional — Guild works without it.

Contradiction policy

confidence: frontmatter field on every page.
Default rule: newer wins unless the older page has confidence: high.
Contradictions are surfaced by guild:wiki-lint, never silently resolved.
You decide on contested high-confidence entries.