Living Knowledge Base

Every AI coding session generates insights — architecture decisions, bug workarounds, dependency quirks — that get lost when the session ends. The Living Knowledge Base captures these into structured entries, compiles them into a project wiki, and feeds them back into future sessions.

The Knowledge Loop

Sessions → Extract (evidence) → Promote (claim) → Compile → Wiki → Agents read & write back

1. AI agents discover facts during coding sessions
2. Facts are saved as knowledge entries (via MCP tools or CLI)
3. Each entry is classified as evidence (raw, from sync), claim (promoted active truth), or note (rejected/dismissed)
4. Compilation auto-promotes qualifying evidence to claim, merges active claims into the project context document
5. Section pages and concept articles are auto-generated from active claims only
6. Future agents read the wiki via get_project_context and contribute back

The loop is self-reinforcing: the more sessions you run, the richer the knowledge base becomes.

The Claim Model (v0.9.8.6+)

Every knowledge entry has a claim_class that controls its lifecycle:

Class	Meaning	When
evidence	Raw fact extracted from a session or submitted by an agent that didn’t meet promotion gates	Default for sync-extracted entries and agent add_knowledge calls
claim	Promoted active truth	Evidence auto-promoted at compile (confidence ≥ 0.5, content ≥ 30 chars), or agent entries that pass specificity + dedup + rate-limit gates
note	Rejected or dismissed — audit-visible but excluded from compile	Manual dismiss, or agent submissions that failed all gates

Freshness decay. Each type has its own decay window applied from last_relevant_at:

Type	Window before stale
bug	30 days
dependency	60 days
pattern, discovery	90 days
convention	180 days
decision	365 days

Past the window, freshness_class moves current → stale → archived. Stale entries are surfaced in the dashboard review queue; only current active claims feed compile by default.

Confidence decay. Claims nobody has referenced for 90 days lose confidence (×0.8), at most once every 30 days. Since v0.23.0 this depends on elapsed time only; before, it was applied on every compile, so frequently compiled projects aged their claims much faster.

Supersession. Retire an old claim in favor of a new one with PUT /api/v1/projects/{id}/entries/{entry_id}/supersede. The old entry remains readable for audit but is excluded from compile.

Refresh. Extend an entry’s validity window with PUT /api/v1/projects/{id}/entries/{entry_id}/refresh — updates last_relevant_at and resets freshness_class to current.

Rebuild. POST /api/v1/projects/{id}/rebuild (or sfs project rebuild) resets compiled_at=NULL on all active claims and clears context_document, forcing a full re-compile on settled projects.

Getting Started

# Initialize a project (auto-detects git remote)
sfs project init

# Add initial context in your editor
sfs project edit

# Enable auto-narrative (generates summaries on sync)
sfs project set --auto-narrative

# Run your first compilation
sfs project compile

After init, the project is linked to your git remote. Every team member with access sees the same knowledge base.

Knowledge Entries

Each entry has a type, content, confidence score (0.0-1.0), and an optional link to the session that created it.

Entry Types

Type	Use For	Example
decision	Architecture and design choices	“WebSockets rejected in favor of HTTP + ETags”
pattern	Code patterns and conventions	“All converters follow parse → canonical → write”
bug	Known issues and workarounds	“SQLite WAL mode can corrupt on power loss”
convention	Coding standards	“All API routes use async handlers”
dependency	External library notes	“react-markdown renders project context, not a custom parser”
discovery	General findings	“The auth middleware resolves tier from org, not user”

Entry Lifecycle

Entries start as pending. After compilation, they become compiled. Irrelevant entries can be dismissed:

# List all entries
sfs project entries

# Filter by type or status
sfs project entries --type decision
sfs project entries --pending

# Dismiss a noisy entry
sfs project dismiss 42

Entries with confidence below 0.5 are marked as (unverified) in the compiled output.

Compilation

Compilation merges pending entries into the project context document and generates section wiki pages.

Pending claims sit in the queue until a compile runs, either on the project’s schedule or by hand.

Scheduled compile (v0.23.0). Each project can compile on a schedule: nightly, weekly or off, optionally also once a number of claims are waiting. Set it under the project’s Settings → Scheduled KB compile or with sfs project compile-schedule weekly --after-claims 20. Scheduled compiles use the deterministic compiler, never an LLM. New projects start at nightly when their plan includes project context; projects created before v0.23.0 start at off. On self-hosted servers the schedule takes effect only once the operator runs the compile sweep. The compile history marks which compiles were manual and which were scheduled.

To compile by hand:

• Dashboard. The project Overview shows when the context was last compiled and how many claims are waiting, with a one-click compile when it is out of date, plus the buttons on the Entries and Context tabs.
• Agent (MCP). Agents are instructed to check get_knowledge_health after writing knowledge, surface the pending count to the user, and call compile_knowledge_base only on explicit consent.
• CLI. sfs project compile from your terminal.

Concurrent compile callers serialize on a project-row lock — duplicate context documents and duplicate concept pages can’t be created by races.

Deterministic Compile (Default)

When no LLM API key is provided, compilation uses a rule-based approach:

• Groups entries by type under structured section headings (## Key Decisions, ## Patterns & Conventions, etc.)
• Appends new entries to the appropriate section
• Marks low-confidence entries as unverified
• Adds a ## Recent Changes section from the current batch

LLM Compile

When an LLM API key is available, the compiler sends the current context plus grouped entries to the model. The LLM deduplicates, reorganizes, and produces a cleaner merged document. Falls back to deterministic compile on failure.

What Happens During Compilation

1. Fetches all pending (not dismissed, not yet compiled) entries
2. Groups them by entry type
3. Merges into the existing context document
4. Marks all processed entries as compiled
5. Saves a before/after snapshot in the compilation history
6. Creates or updates section pages in the wiki (one per entry type)
7. Auto-generates concept articles for recurring topics

sfs project compile
# Compiling pending entries...
# Project context updated. 12 entries compiled.

Section Pages

Each entry type gets its own wiki page, auto-generated from all non-dismissed entries of that type:

Entry Type	Wiki Page Slug
decision	key-decisions
pattern	patterns
convention	coding-conventions
bug	known-issues
dependency	dependencies
discovery	discoveries

Wiki Pages

The wiki is a collection of markdown pages organized by slug. Pages can be manually written or auto-generated from knowledge entries.

Browsing

# List all wiki pages
sfs project pages
# Slug            Title                  Type      Words  Entries  Auto
# key-decisions   Key Decisions          section     340       18  yes
# patterns        Patterns               section     210       12  yes
# architecture    Architecture Overview  section     890        0  no

# Read a specific page
sfs project page key-decisions

Concept Auto-Generation

After compilation, the system identifies recurring topics across entries and generates concept articles. These are standalone wiki pages that synthesize related entries into a coherent narrative.

Regeneration

Auto-generated pages can be regenerated from the latest entries:

sfs project regenerate key-decisions
# Article regenerated (340 words from 18 entries).

Only auto-generated pages support regeneration. Manually written pages are left untouched.

Backlinks

Pages track which entries and other pages reference them. View backlinks at the bottom of any page:

sfs project page architecture
# [content rendered in panel]
#
# Backlinks:
#   entry:42 (references)
#   entry:67 (references)

CLI Commands

Command	Description
sfs project init	Initialize project context for the current repo
sfs project compile	Compile pending entries into the context document
sfs project rebuild	Force a full re-compile (reset compiled_at=NULL + clear context document)
sfs project entries	List knowledge entries (supports --pending, --type, --limit)
sfs project ask "question"	Search the knowledge base and show matching entries
sfs project pages	List all wiki pages
sfs project page <slug>	View a wiki page with backlinks
sfs project health	Run health checks — pending count, staleness, score
sfs project regenerate <slug>	Regenerate an auto-generated concept page
sfs project set --auto-narrative	Enable auto-narrative summaries on sync
sfs project dismiss <id>	Dismiss an irrelevant entry
sfs project edit	Edit the context document in $EDITOR
sfs project show	Display the current context document

Health Checks

The health command scores your knowledge base and flags issues:

sfs project health
# Project Health: my-project
#
#   ✓  Context document exists (1200 words, 8 sections)
#   ✓  45 knowledge entries (38 compiled, 2 dismissed)
#   ⚠  5 entries pending compilation
#   ✓  Last compiled: 2026-04-01
#   ✓  Context appears up to date
#
# Health Score: 90%

MCP Integration

The SessionFS MCP server exposes five knowledge-related tools that AI agents call during sessions.

Write Tools

Tool	Description
add_knowledge(content, entry_type)	Add a knowledge entry. Optional: session_id, confidence (0.0-1.0)
update_wiki_page(slug, content)	Create or update a wiki page. Optional: title
list_wiki_pages()	List all wiki pages with slugs, titles, and word counts

Read Tools

Tool	Description
search_project_knowledge(query)	Search entries by content. Optional: entry_type, limit
ask_project(question)	Research a question across context, entries, and local sessions

How Agents Contribute

When an agent calls get_project_context, the response includes contribution instructions. Agents are expected to call add_knowledge() when they discover something significant:

# Example: agent discovers a pattern during a session
add_knowledge("All CLI commands use the @handle_errors decorator for consistent error handling", "pattern")

The entry is stored as pending until the next compilation cycle.

API Endpoints

All endpoints are under /api/v1/projects/{project_id} and require authentication.

Method	Path	Description
GET	/entries	List entries. Query params: type, pending, search, limit
GET	/entries/search	Search active claims by default. Pass include_stale=true to include evidence, notes, and superseded entries
POST	/entries/add	Add a single entry. Body: content, entry_type, confidence, session_id, entity_ref, upsert (default: false), claim_class (default: note). When upsert=true AND entity_ref is set, the write is a state-cache roll-forward: similarity dedup is skipped, the new row commits, and any active prior entry sharing the same entity_ref in this project is auto-dismissed with superseded_by=<new_id> + supersession_reason="entity_ref upsert". Response includes upserted_from: [prior_ids] so callers can audit. upsert=true without entity_ref returns 422. Default upsert=false preserves the existing entity_ref semantic where multiple distinct claims about the same entity coexist (compile-time _auto_supersede reasons about them). Cross-project isolation: the upsert query is scoped by project_id, so writing the same entity_ref from another tenant is invisible.
PUT	/entries/{entry_id}	Dismiss or un-dismiss an entry
PUT	/entries/{entry_id}/refresh	Reset last_relevant_at and freshness_class=current. Replaces the old “Still valid” no-op
PUT	/entries/{entry_id}/supersede	Retire an old claim and link it to a superseding entry. Body: superseded_by_id, reason
POST	/entries/dismiss-stale	Bulk-dismiss low-confidence stale entries (confidence < 0.5 + > 90 days unreferenced)
POST	/compile	Compile pending entries. Auto-promotes evidence ≥ 0.5 confidence to claim before merging
POST	/rebuild	Reset compiled_at=NULL on all active claims and clear context_document to force a full re-compile
GET	/compilations	List compilation history (each marked manual or scheduled)
GET	/compile-status	Last compile, claims waiting, and whether a compile is recommended (v0.23.0)
GET	/health	Health status: entry counts, staleness, word count, score inputs, stale review queue
GET	/pages	List wiki pages
GET	/pages/{slug}	Get page content with backlinks
PUT	/pages/{slug}	Create or update a page. Body: content, title
DELETE	/pages/{slug}	Delete a wiki page
POST	/pages/{slug}/regenerate	Regenerate an auto-generated page
PUT	/settings	Update project settings (e.g., auto_narrative, kb_max_context_words — default 2000)

Best Practices

When to compile. Run sfs project compile after batches of sessions, not after every single entry. A good cadence is weekly or after a feature sprint. The health command tells you when pending entries are piling up.

Seed the knowledge base early. Before your first AI session, add a few decision and convention entries manually via the API or MCP tools. This gives agents immediate context and sets the tone for the kind of knowledge you want captured.

Dismiss noise aggressively. Not every discovery is worth keeping. Dismiss trivial entries (sfs project dismiss <id>) so they don’t clutter compiled output. The confidence score helps — entries below 0.5 are flagged as unverified.

Use upsert=true + entity_ref for state caches. When an autonomous agent needs durable append-only state (e.g. an LRU map of “signals already classified”), pass upsert=true alongside a stable entity_ref like signal-state:decisions. The server skips the similarity-dedup gate, commits the new entry, and auto-dismisses any prior active row sharing that entity_ref (superseded_by=<new_id>). The response surfaces upserted_from: [prior_ids] so the caller can confirm the roll-forward. Default upsert=false preserves the normal entity_ref semantic — multiple distinct claims about the same entity coexist, and compile-time _auto_supersede reasons about them. Use upsert ONLY for state-cache slots, never for natural KB entries.

Use wiki pages for depth. Knowledge entries are single facts. For topics that need explanation — architecture, deployment, onboarding — create wiki pages via update_wiki_page() or the dashboard editor.

Monitor health regularly. A healthy project has a score above 80%, no stale context, and fewer than 10 pending entries. Run sfs project health in CI or as a periodic check.

Let auto-narrative do its job. With --auto-narrative enabled, session summaries are extracted on sync and stored as entries automatically. This is the lowest-effort way to build the knowledge base — just use your AI tools normally.