Docs

Context & Memory

How FlyDocs manages project context, session continuity, knowledge graphs, and cross-repo awareness.

Your agent orients itself to the full project in seconds. It remembers previous sessions, understands how this repo fits into the larger system, and knows what decisions were made and why. You stop re-explaining your project every conversation.

This is not a chat history. It is a layered system of project knowledge, relationship graphs, service descriptors, and session summaries that compounds over time. Every session builds on the last instead of starting from scratch.

Project context

flydocs/context/project.md is the foundation. It captures your project's scope, tech stack, conventions, coding standards, and current priorities. On the cloud tier, it is AI-generated from your repository during setup (via the portal's repo scanning) and refined during onboarding. On the local tier, it is generated from templates. Either way, it is loaded before every prompt via the context injection hook.

flydocs/context/project.md 
# Project Name

## What This Is
A SaaS platform for team collaboration. Deploys to app.example.com
as a Next.js application with a PostgreSQL backend.

## Stack
- **Framework**: Next.js 15.x (App Router)
- **Database**: PostgreSQL via Prisma ORM
- **Auth**: NextAuth.js with OAuth providers
- **Styling**: Tailwind CSS v4

## Standards
- TypeScript strict mode, no `any`
- Server Components by default, Client Components only for interactivity
- All API routes validated with Zod schemas

## Active Priorities
1. Multi-tenant workspace support (in progress)
2. Real-time notifications via WebSockets
3. Audit logging for compliance

The context injection hook (UserPromptSubmit) reads this file and injects it before every prompt. The AI starts every interaction knowing what the project is, what stack it uses, what standards to follow, and what work is currently active. No manual preamble needed.

Session continuity

The SessionStart hook automatically injects the previous session summary when a new conversation begins. Cross-session continuity is built-in, not opt-in. The AI knows what happened last time without being told.

Two slash commands bookend each work session:

  • /start-session loads project context, active issues, recent progress, and the previous session summary. It sets up the working context so the AI is ready to continue where you left off.
  • /wrap-session captures what happened during the session: progress made, decisions taken, blockers hit, and next steps. It posts a project update and records the session in the context graph.

This creates a continuity chain. Each session builds on the last instead of starting from scratch. The AI does not just know what you did yesterday -- it knows how yesterday's work relates to today's priorities.

Context graph

The context graph tracks relationships between skills, decisions, sessions, issues, and project knowledge. It is not a flat file -- it understands how things connect.

Relationship Graph

SESSION
Yesterday's work
RELATES_TO
DECISION
ADR-001
PRODUCED
INFORMS
KNOWLEDGE
Migration notes
GUIDES
ISSUE
Today's work

The graph is managed through three scripts:

Terminal 
# Build the context graph from skills, ADRs, and service descriptors
python3 .claude/skills/flydocs-workflow/scripts/graph_build.py

# Query relationships from a specific node
python3 .claude/skills/flydocs-workflow/scripts/graph_query.py \
  --node "flydocs-workflow" --depth 2 --format md

# Record session context into the graph
python3 .claude/skills/flydocs-workflow/scripts/graph_session.py \
  --summary "Implemented workspace settings page" \
  --issue ENG-123 --decision 004
  • graph_build.py rebuilds the graph from skills, ADRs, service descriptors, and project knowledge
  • graph_query.py performs BFS traversal from any node, returning related nodes up to a specified depth
  • graph_session.py records session context -- called during /wrap-session to link the session to the issues worked on and decisions made

When the context injection hook fires, it queries the graph for relevant context based on the active issue and recent sessions. The AI does not just see a flat list of documents -- it sees how they relate to the current work.

Service descriptors

flydocs/context/service.json provides cross-repo context for multi-repo workspaces. It describes what the current repository is, what it depends on, and how it relates to sibling services.

flydocs/context/service.json 
{
  "name": "flydocs-marketing",
  "type": "web-frontend",
  "framework": "astro",
  "topology": "sibling-repos",
  "relationships": [
    { "target": "flydocs-core", "type": "depends-on" },
    { "target": "flydocs-app", "type": "sibling" }
  ]
}

FlyDocs detects your repository topology automatically:

  • Single app: one repository, one service
  • Monorepo: multiple services in one repository
  • Sibling repos: related repositories that share a workspace

For multi-repo setups, push_service.py publishes the local service descriptor to the relay, and pull_services.py pulls a workspace composite that describes all services. This gives the AI cross-repo awareness -- it knows that the marketing site depends on the core framework, or that the API service is a sibling of the web application.

In a multi-repo workspace, .flydocs-workspace.json at the workspace root provides the full topology index: per-repo purpose, stack, and dependency graph. The agent reads this to understand the entire system architecture before diving into any single repo. See Workspaces & Topology for more detail on how topology detection and cross-repo context work.

Knowledge base

flydocs/knowledge/ is a growing repository of decisions, notes, and project documentation. Anything worth remembering goes here. The AI consults it when making decisions, so institutional knowledge compounds over time instead of resetting every session.

Directory Structure 
flydocs/knowledge/
├── decisions/
│   ├── 001-auth-provider.md      # Why we chose NextAuth over Clerk
│   ├── 002-database-orm.md       # Why Prisma over Drizzle
│   └── 003-state-management.md   # Why Zustand over Redux
├── notes/
│   ├── api-rate-limiting.md      # Research on rate limiting approaches
│   └── migration-strategy.md     # Database migration patterns
└── VISION.md                     # Product vision and long-term direction
  • Decisions (ADRs): Architectural decisions with context, options considered, and rationale. The AI references these before making similar decisions.
  • Notes: Technical research, migration strategies, integration guides. Working knowledge that does not fit into a formal decision record.
  • Vision: Product direction and long-term goals. Helps the AI make choices aligned with where the product is heading, not just where it is today.

The /knowledge command captures new entries during development. When the AI makes a significant decision or discovers something worth recording, it creates a knowledge entry that future sessions can reference.

Next