Shared Project Context

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

One document per repository — matched by git remote URL (SSH and HTTPS both work)
Shared across the team — anyone with sessions in the repo can read and edit
Accessible via MCP — AI agents call get_project_context to read the document and add_knowledge to contribute back
Auto-compiled from entries — knowledge entries from sessions are merged into the document during compilation
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.

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.

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 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 22 tools, including several for project context, knowledge, and rules. When connected, AI agents can read the shared document, contribute knowledge entries, update wiki pages, fetch canonical rules, and trigger a compile pass. 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 when using the local MCP server. For the remote MCP server, pass the git remote 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