Shared Project Context

Tip

Project context is one part of the Living Knowledge Base. Entries accumulate from sessions, get compiled into this document, and generate wiki pages. See Living Knowledge Base for the full loop.

Share a single source-of-truth document with every AI agent working on your codebase. Any teammate, on any device, using any AI tool with the SessionFS MCP server, gets the same project context.

As of v0.9.7, the context document is auto-compiled from knowledge entries — not just manually edited. You can still edit it directly, but the recommended workflow is to let entries accumulate from sessions and compile them into the document periodically.

Quick Start

# From inside your git repo
sfs project init
sfs project edit          # Opens in $EDITOR

# Other teammates can now see it
sfs project show

How It Works

1. One document per repository — matched by git remote URL. Every spelling of the same remote (HTTPS, ssh://, git://, scp style such as git@github.com:org/repo, with or without .git or a trailing slash) maps to the same project
2. Shared across the team — anyone with sessions in the repo can read it and add to it; the owner and the project’s org members can change it (see Who can change a project)
3. Accessible via MCP — AI agents call get_project_context to read the document and add_knowledge to contribute back
4. Auto-compiled from entries — knowledge entries from sessions are merged into the document during compilation
5. Free-form markdown — you can still edit directly; compiled content and manual edits coexist

The Compile Workflow

Sessions sync → entries extracted → entries accumulate (pending)
                                          ↓
                              sfs project compile
                                          ↓
                        context document updated + wiki pages generated

Knowledge entries build up as pending until you run sfs project compile. Compilation merges them into the context document and generates wiki section pages. You control the cadence — compile after a sprint, weekly, or whenever sfs project health tells you entries are piling up.

Who can change a project

Anyone who can see a project can read it and add to it. Changing it is limited to its owner and its organization.

Who	Read	Add (knowledge entries, tickets, comments, agent runs, feedback)	Change (settings, rules, wiki pages, context document, knowledge curation, personas, work queues)
Project owner	Yes	Yes	Yes
Member of the project’s organization (any role)	Yes	Yes	Yes
Anyone else who synced a session from the same repository	Yes	Yes	No

What people in the last row add waits for the owner or an org member:

• Their knowledge entries stay notes (confidence at most 0.7), are never promoted or allowed to supersede other entries automatically at compile time, and so don’t reach the context document or compiled rules files until an owner or org member promotes them. Bulk promote leaves their notes out unless include_reader_notes is set. An add_knowledge call with upsert=true (which retires the other entries in its slot) needs change rights.
• Their tickets start as suggested. The assignee isn’t notified and autonomous work queues don’t pick the ticket up until an owner or org member approves it.
• They can keep editing tickets they created. Editing one after it was approved sends it back to suggested for approval again. Once work has started, or a work queue has picked the ticket up, they can only change its reference lists (context refs, file refs, related sessions). A work queue doesn’t hand out a ticket that is back in suggested (or cancelled) until an owner or org member approves it again.
• Their comments are visible to people in the dashboard, API and MCP tools, but aren’t passed to automated agents: work queues leave them out of the comments they send to agents, and they don’t start a reviewer’s turn.
• On tickets they can dismiss, reopen or accept tickets they created (but not accept work they resolved themselves), and start, complete, block or unblock tickets they created or resolved. Approving a suggested ticket needs change rights.
• They can cancel or complete agent runs they triggered, but not anyone else’s.
• A rules compile they run returns the compiled files without adding a version to the rules history.
• Project-scope skill install requests need change rights; personal (user or device) requests don’t. A change they try gets 403 project_edit_forbidden, and the dashboard hides the controls they can’t use (the project response carries can_edit). Renaming, linking repositories, merging, transferring and deleting still need project-admin standing (the owner, or an org owner or admin). Service keys keep their own boundary: the key’s organization and project allowlist.

CLI Commands

sfs project init

Create a project context for the current repository. Detects the git remote automatically.

cd ~/code/my-project
sfs project init
# Project created for myorg/my-project
# Run 'sfs project edit' to add context.

sfs project edit

Open the context document in your editor. Changes are uploaded on save.

sfs project edit
# Opens in $EDITOR (default: nano)

Set your preferred editor:

export EDITOR=vim
# or
export EDITOR="code --wait"

sfs project show

Display the current project context with metadata.

myorg/my-project

sfs project show
# Project: my-project
# Updated: 2026-03-26
#
# # Architecture
# ...

sfs project set-context

Set the context from a file (useful for CI or scripting).

sfs project set-context ./PROJECT_INSTRUCTIONS.md
# Project context updated (2.4 KB).

sfs project get-context

Output raw markdown to stdout (useful for piping).

sfs project get-context > local-copy.md

sfs project compile

Compile pending knowledge entries into the context document and generate wiki pages. Uses deterministic merging by default; pass an LLM API key for smarter deduplication and reorganization.

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

sfs project compile-schedule

Compile the project’s knowledge on a schedule instead of by hand: nightly, weekly or off, optionally with a waiting-claims threshold (v0.23.0). The same setting is under the project’s Settings → Scheduled KB compile. Scheduled compiles use the deterministic compiler, never an LLM.

sfs project compile-schedule weekly --after-claims 20
sfs project compile-schedule off --no-after-claims

New projects start at nightly when their plan includes project context; existing projects start at off. 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. On a self-hosted server the schedule only takes effect once the operator runs the compile sweep.

sfs project health

Check the health of your project’s knowledge base — pending entry count, staleness, document size, and an overall score.

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
#
# Health Score: 90%

Auto-Narrative

Enable auto-narrative to have session summaries extracted as knowledge entries automatically on sync. This is the lowest-effort way to keep the context document current — just use your AI tools normally and let entries accumulate.

sfs project set --auto-narrative

When enabled, each synced session is analyzed for decisions, patterns, bugs, and other notable facts. Extracted entries are stored as pending until compilation. Requires an LLM API key (client-side — SessionFS never stores your key).

MCP Integration

The SessionFS MCP server exposes 145 tools, including several for project context, knowledge, rules, personas, tickets, CI agent runs, agent feedback, handoffs (Pro+ for direct, Team+ for team handoffs), autonomous work queues, project groups (Team+), and the skills marketplace. When connected, AI agents can read the shared document, contribute knowledge entries, update wiki pages, fetch canonical rules, manage personas, run a ticket through its full FSM, record AgentRun outcomes, create + claim coordination handoffs with provenance carry-through, service a work queue of tickets unattended, and search, preview, and request installs of skill packages. This works with any MCP-aware tool (Claude Code, Cursor, etc.).

Tool	Description
get_project_context	Read the compiled context document
add_knowledge(content, type)	Contribute a knowledge entry
update_wiki_page(slug, content)	Create or update a wiki page
list_wiki_pages()	List all wiki pages
search_project_knowledge(query)	Search entries by content
ask_project(question)	Research a question across context, entries, and sessions

The tools auto-detect the git remote from the current working directory; you can also pass it explicitly as an argument.

What to Include

The default template provides a starting structure:

# Project Context

## Overview
What is this project? One paragraph.

## Architecture
Tech stack, infrastructure, key services.

## Conventions
Coding standards, branch strategy, PR process.

## API Contracts
Key endpoints, request/response formats.

## Key Decisions
Important decisions that are locked and shouldn't be revisited.

## Team
Who works on what.

Write whatever is useful for your team. Some ideas:

• Database schema overview
• Deployment process
• Testing conventions
• Security requirements
• Third-party service credentials (names only, not values)
• Links to external documentation

Access Control

• Read: Any authenticated user with sessions in the repository
• Write: Same as read (team trust model)
• Owner: The user who ran sfs project init

API Endpoints

Method	Path	Description
POST	/api/v1/projects/	Create a project context
GET	/api/v1/projects/{remote}	Get project context by git remote
PUT	/api/v1/projects/{remote}/context	Update the context document
GET	/api/v1/projects/{id}/compile-status	Last compile, claims waiting, and whether a compile is recommended (v0.23.0)