Knowledge Management

This skill manages a persistent knowledge graph stored as markdown files under .claude/context-graph/. It captures architectural knowledge, component relationships, design decisions, and infrastructure details in a structured, navigable format.

What Is the Context Graph?

The context graph is a directory of interconnected entity files. Each entity represents a meaningful unit of project knowledge (a component, a data model, a decision, an integration, etc.) and declares typed relationships to other entities using [[link]] syntax. An index.md file at the root provides a table of contents.

.claude/context-graph/
  index.md                    # Table of contents: all entities by type
  schema.md                   # Entity types and relation types used
  map.mermaid                 # Visual graph (generated by /context-map)
  entities/
    auth-service.md           # Type: component
    user-model.md             # Type: data-model
    adopt-jwt-tokens.md       # Type: decision
    postgres-primary.md       # Type: infrastructure
    stripe-integration.md     # Type: integration
    project-overview.md       # Type: project-context

How It Differs from Session Resilience

Aspect	Session Resilience	Context Graph
Scope	Single session state	Permanent project knowledge
Lifetime	One session (survives compression)	All sessions (survives forever)
Content	Decisions, tasks, next steps for this session	Components, models, architecture, relations
Trigger	PreCompact, /checkpoint	/context-bootstrap, /context-add, PreCompact
Growth	Replaced each session	Accumulated over project lifetime
Location	.claude/session-state.md	.claude/context-graph/ directory

They are complementary: session-resilience tracks "what am I doing right now," while the context graph tracks "what does this project look like."

Entity Model

Every entity is a markdown file in .claude/context-graph/entities/ that follows the schema defined in references/entity_schema.md.

Entity Types

Type	Purpose	Examples
component	A module, service, or subsystem	auth-service, payment-processor, api-gateway
data-model	A database table, schema, or data structure	user-model, order-schema, event-payload
decision	An architectural or design decision	adopt-jwt-tokens, use-postgres, monorepo-structure
infrastructure	A deployment, hosting, or ops resource	postgres-primary, redis-cache, k8s-cluster
integration	An external service or API integration	stripe-integration, sendgrid-email, github-webhooks
project-context	High-level project info, conventions, constraints	project-overview, coding-standards, team-structure

Relation Types

Relation	Meaning	Example
depends-on	Requires this entity to function	auth-service depends-on user-model
consumed-by	This entity is used by another	user-model consumed-by auth-service
decided-by	Governed by this decision entity	auth-service decided-by adopt-jwt-tokens
replaces	Supersedes a deprecated entity	jwt-auth replaces session-cookies
implements	Realizes this specification or design	auth-service implements oauth2-spec
tested-by	Has associated test coverage	auth-service tested-by auth-integration-tests

When to Create Entities

Create a new entity when:

1. A major component, service, or module is discovered that is central to the architecture
2. A significant design decision is made with rationale worth preserving
3. A data model is defined that multiple components interact with
4. An external integration is configured or discovered
5. Infrastructure details are identified that affect development

Do NOT create entities for:

• Individual functions or utility methods (too granular)
• Temporary experiments or throwaway code
• Configuration values that change frequently (use environment docs instead)
• Entities that duplicate information already in the codebase README

When to Update Entities

Update an existing entity when:

1. New dependencies are discovered between components
2. Status changes (active to deprecated, planned to in-progress)
3. Ownership changes
4. New files are associated with the entity
5. Relations to new entities are established

How to Navigate the Graph

See references/navigation_patterns.md for full traversal strategies. The short version:

1. Start at index.md — find the entity by name or type
2. Read the entity file — get summary, properties, and relations
3. Follow [[links]] — traverse to related entities for context
4. Grep for tags — find entities by keyword when the name is unknown
5. Read map.mermaid — see the visual dependency graph

File Locations

• Graph root: .claude/context-graph/
• Entity files: .claude/context-graph/entities/
• Index: .claude/context-graph/index.md
• Schema: .claude/context-graph/schema.md
• Visual map: .claude/context-graph/map.mermaid

Always use these canonical paths. Do not create entity files outside the entities/ directory.

Important Rules

1. Entity names use kebab-case. The filename is the entity identifier: auth-service.md is entity auth-service. See references/graph_conventions.md.

2. Links use double-bracket syntax. Reference other entities as [[entity-name]]. The validator checks that linked entities exist.

3. Every entity has a Type field. Must be one of the six defined types. The PostToolUse hook validates this on every write.

4. Relations are bidirectional in intent. If A depends-on B, then B should have a consumed-by A relation. Keep both sides in sync.

5. The index must stay current. After adding, renaming, or removing entities, update index.md to reflect the change.

6. Prune stale entities. Use /context-prune periodically to identify entities whose referenced files no longer exist or that have no inbound relations.