Project memory and wiki, Guild Stack

Guild Stack remembers a project through files you can inspect and review. Durable decisions, standards, constraints, and source-backed facts live under .guild/wiki/**. That wiki is the canonical memory. Specialists recall it, reviewers audit it, and you can change it through the same repo workflow you use for code.

Everything else is derived. The KnowledgeGraph, knowledge links, knowledge-recall.json, codebase maps, and index.sqlite help Guild Stack retrieve and traverse knowledge, but they are rebuildable. Deleting a derived index loses speed or structure, not source truth.

Try it: /guild:wiki query "<topic>" searches the project wiki without writing to memory.

Knowledge lifecycleroute_knowledge_flow

Run evidenceobserved fact
Candidatesourced proposal
Human gateapprove or archive
Wikicanonical memory
Recallgraph + index + cache

Memory flows through a gate: runs produce evidence, candidates are proposed, humans promote, and derived recall artifacts rebuild from the canonical wiki.

Source-backed contract

This page follows docs/v2/workspace-federation.md, knowledge-memory.md, codebase-understanding.md, and architecture/modules/knowledge.md.

Contract	What it means	Proof surface
The wiki is canonical	Durable project memory lives in Markdown under `.guild/wiki/**`.	Wiki pages, decisions, standards, and source refs.
Raw sources remain provenance	Ingested source material lives beside the wiki and is cited from wiki pages.	`.guild/raw/sources/**` and `source_refs:`.
Learning proposes	Run facts and learning checkpoints create candidates; they do not promote knowledge.	`.guild/runs/<run-id>/learn/harvest-candidates.json`.
Human gates write canon	Significant choices go through `guild:decisions`; sourced knowledge goes through `guild:wiki-ingest`.	`.guild/wiki/decisions/**` and promoted wiki pages.
Derived state is rebuildable	Graphs, links, recall projections, and SQLite caches are regenerated from filesystem artifacts.	`.guild/indexes/**` and `.guild/index.sqlite`.
Workspace knowledge is federated	Workspace facts live in the umbrella wiki; project facts stay in project wikis and are queried in place.	`workspace.json` query recipe plus source-tagged recall results.

Canonical vs derived

Treat this table as the memory map.

Surface	Canonical?	Role	Rebuild behavior
`.guild/wiki/**`	Yes	Durable decisions, standards, context, product facts, concepts, entities, and source summaries.	Edited or promoted by human-gated flows.
`.guild/raw/sources/**`	Yes	Immutable source provenance for ingested material.	Preserved as audit trail.
`.guild/runs/<run-id>/**`	Record	Per-run evidence, receipts, provenance, handoffs, and learning candidates.	Run record remains evidence; selected facts may become candidates.
`.guild/indexes/codebase-map.json`	No	Derived structural inventory.	Rebuilt by learn/map flows.
`.guild/indexes/knowledge-graph.json`	No	Derived code/wiki graph owned by the learn engine.	Rebuilt or refreshed from repo + wiki evidence.
`.guild/indexes/knowledge-links.json`	No	Derived work/decision edge layer.	Rebuilt from wiki, raw sources, and run provenance.
`.guild/indexes/knowledge-recall.json`	No	Nonce-free recall projection used by recall scoring.	Rebuilt by the learn knowledge finalize path.
`.guild/index.sqlite`	No	Local cache for larger wiki, graph, links, and provenance reads.	Droppable; direct filesystem parsing is the fallback.

docs/knowledge/ is retired. It was a v2 design and research store, not the active knowledge canon. Durable content was harvested into .guild/wiki/**, and historical reference may remain under .guild/wiki/_archive/v2-design/.

Beginner path: where decisions live

If you are new to Guild Stack, start with one question: “Should this affect future runs?”

If the answer is…	Put it here
”This is an important choice or answer we should remember.”	`.guild/wiki/decisions/<slug>.md` through `guild:decisions`.
”This is a standard future agents should follow.”	`.guild/wiki/standards/<slug>.md` through `guild:wiki-ingest` or a reviewed edit.
”This is project background.”	`.guild/wiki/context/<slug>.md`.
”This is source material we may cite later.”	`.guild/raw/sources/<slug>/` plus a wiki summary with `source_refs:`.
”This only explains what happened in one run.”	Leave it in `.guild/runs/<run-id>/`.

Trivial Q&A can stay in the transcript or run record. Medium- or high-impact answers should become decisions so future specialists and reviewers can recall them.

What belongs in the wiki

.guild/wiki/
├── index.md
├── log.md
├── context/
├── standards/
├── products/
├── entities/
├── concepts/
├── decisions/
└── sources/

Category	Use it for	Loaded when
`context/`	Slow-moving project identity, goals, non-goals, and constraints.	Broad project context.
`standards/`	Normative rules for code, writing, brand, SEO, pricing, or operations.	Matching specialist roles.
`products/`	Product-level facts, feature behavior, customer-facing rules.	A task touches that product or feature.
`entities/`	Teams, people, vendors, services, customers, and named systems.	The entity is named or relevant.
`concepts/`	Architectural patterns, domain models, and reusable ideas.	The concept matches the task.
`decisions/`	ADR-lite choices, Q&A captures, superseding records.	Rationale, constraints, or previous answers matter.
`sources/`	Summaries of raw ingested materials with citations.	A task needs provenance-backed context.

External content is data, not instructions. A source can inform a wiki page, but imperative language inside an external document does not become a project rule unless a human promotes it into standards/ or context/.

Page frontmatter contract

Durable wiki pages carry frontmatter so recall, lint, and graph projections can filter and audit them:

---
type: context | standard | product | entity | concept | decision | source
owner: orchestrator | architect | backend | copywriter | ...
confidence: low | medium | high
importance: critical | high | medium | low
labels:
  domain: []
  concern: []
  status: active | superseded | deprecated
trust_tier: reviewed | synthesized | untrusted
source_refs: []
created_at: 2026-04-24
updated_at: 2026-04-24
expires_at: null
supersedes: null
sensitivity: public | internal | confidential | secret
---

confidence says how certain the page is. importance says how central it is. Those are separate axes: a fact can be true but peripheral, or still evolving but central enough that future work must see it. labels: are the project vocabulary used by recall and lint when a taxonomy exists.

Promotion path

Guild Stack does not pour every observation into durable memory.

A run records evidence under .guild/runs/<run-id>/.
Reflection and learning checkpoints propose candidates.
guild:decisions captures significant choices, or guild:wiki-ingest promotes sourced knowledge.
guild:wiki-lint reports contradictions, stale pages, missing refs, and category issues.

LearningCheckpoint is automatic and advisory. It rides the existing phase review boundary, often emits an all-none no-op, never auto-promotes wiki pages, and never changes permission, sandbox, runtime, or security policy.

Wiki operations

Operation	What it does	Writes canon?
`guild:wiki-ingest`	Promotes an approved source into wiki knowledge and raw provenance.	Yes, through the human-gated path.
`guild:wiki-query`	Searches project memory for an operator or task.	No.
`guild:wiki-lint`	Reports contradictions, stale claims, missing refs, orphan pages, and label issues.	No; it writes a report, not canon.
`guild:decisions`	Captures durable decisions and important Q&A.	Yes, under `.guild/wiki/decisions/**`.

/guild:wiki ingest <path-or-url>
/guild:wiki query "event sourcing decision"
/guild:wiki lint

The optional guild-memory MCP server is read-only. It exposes wiki_search, wiki_get, and wiki_list over .guild/wiki/**; it is not the system of record and does not write pages. Hosts or modes without MCP fall back to filesystem recall.

Recall into specialist work

Recall-before-read turns the wiki into working context instead of an archive. Before a specialist reads files, context assembly builds a bounded bundle from:

Layer	Protected?	Holds
Universal	Partly	Project identity, task goal, and conventions every lane needs.
Role	Yes	Specialist standards and protected role guidance.
Task	Droppable first	Matched wiki pages, decisions, derived graph or recall projection chunks, and initiative summary when attached.

Under budget pressure, derived graph nodes are shed before pinned decisions or role content. Omissions are named with dropped_for_budget: rather than hidden.

Harness reference: schemas and rebuildability

Harness Developers should depend on contracts and file maps, not on cache contents.

Contract	Path	Owner
Wiki page frontmatter	`.guild/wiki/*/.md`	Knowledge and decisions flows.
`guild.harvest_candidates.v1`	`.guild/runs/<run-id>/learn/harvest-candidates.json`	Learn harvest.
`guild.knowledge_links.v1`	`.guild/indexes/knowledge-links.json`	Knowledge-links builder.
`guild.knowledge_links.v2` recall projection	`.guild/indexes/knowledge-recall.json`	Learn knowledge finalize path.
`guild.knowledge_graph.v1/v2`	`.guild/indexes/knowledge-graph.json`	Learn engine.
SQLite cache schema	`.guild/index.sqlite`	State and migrations modules.

Public extension points are the commands, wiki files, raw sources, and declared schemas. Internals include the BM25 scorer, graph scoring, ingest-importance stamper, SQLite population engine, and learn K-stage orchestration. They are allowed to evolve as long as the filesystem-canonical contract holds.

Rebuild rules:

If this disappears	What happens
`knowledge-graph.json`	Learn can rebuild or refresh it from repo and wiki evidence.
`knowledge-links.json`	The edge layer can rebuild from wiki, raw sources, and run provenance.
`knowledge-recall.json`	The recall projection can rebuild from the graph and config.
`index.sqlite`	Guild Stack falls back to direct filesystem parsing and repopulates lazily.
`.guild/wiki/**`	Source truth is lost unless restored from version control or backup.

That last row is the key invariant: the wiki is the memory. Indexes and caches serve recall; they do not own truth.

Workspace note

In a standalone project, the project’s .guild/wiki/** is canonical for that project. In a workspace, cross-repo facts live in the umbrella .guild/wiki/** and project-specific facts stay in the child project’s wiki. The workspace queries child wikis in place and tags the results; it does not copy child wiki pages upward.

Page evidence and guidance