guardkit graphiti add-context¶

Add context to Graphiti from markdown files or directories.

Overview¶

The guardkit graphiti add-context command adds content from markdown files to the Graphiti knowledge graph. It uses specialized parsers to extract structured information from different document types (ADRs, feature specs, project overviews) and creates episodes that can be semantically searched.

Usage¶

guardkit graphiti add-context [OPTIONS] <PATH>

Arguments¶

Argument	Description
PATH	File or directory to add (required)

Options¶

Option	Short	Description	Default
`--type TEXT`		Force specific parser type	Auto-detect
`--force`	`-f`	Overwrite existing context	false
`--dry-run`		Preview without making changes	false
`--pattern TEXT`		Glob pattern for directories	`*/.md`
`--verbose`	`-v`	Show detailed processing output	false
`--quiet`	`-q`	Suppress non-error output	false

Note: --verbose and --quiet are mutually exclusive.

Examples¶

Add a Single File¶

# Add an Architecture Decision Record
guardkit graphiti add-context docs/architecture/ADR-001-use-graphiti.md

# Add a feature specification
guardkit graphiti add-context docs/features/FEATURE-SPEC-authentication.md

# Add project overview
guardkit graphiti add-context CLAUDE.md

Add Multiple Files from Directory¶

# Add all markdown files in directory (recursive)
guardkit graphiti add-context docs/architecture/

# Add only ADR files
guardkit graphiti add-context docs/ --pattern "ADR-*.md"

# Add all feature specs
guardkit graphiti add-context docs/ --pattern "**/FEATURE-SPEC-*.md"

Force Specific Parser¶

# Treat file as ADR even if filename doesn't match pattern
guardkit graphiti add-context custom-decision.md --type adr

# Force project-overview parser
guardkit graphiti add-context overview.md --type project-overview

# Force feature-spec parser
guardkit graphiti add-context spec.md --type feature-spec

Preview Mode (Dry Run)¶

# See what would be added without actually adding
guardkit graphiti add-context docs/ --dry-run

# Dry run with verbose output to see all episodes
guardkit graphiti add-context docs/ --dry-run --verbose

Verbose Output¶

# Show detailed parsing information
guardkit graphiti add-context docs/ --verbose

# Output includes:
# - Which parser is used for each file
# - Number of episodes extracted
# - Episode IDs and types
# - Warnings and errors

Quiet Mode¶

# Suppress all output except errors (for automation)
guardkit graphiti add-context docs/ --quiet

# Shows only:
# - Fatal errors
# - Warnings (always shown even in quiet mode)

Overwrite Existing Content¶

# Update existing episodes with new content
guardkit graphiti add-context docs/ADR-001.md --force

# Useful when:
# - ADR status changed (Proposed → Accepted)
# - Feature spec updated with new tasks
# - Project overview modified

Output¶

Standard Output¶

Graphiti Add Context

Connected to Graphiti

  ✓ docs/architecture/ADR-001.md (adr)
  ✓ docs/features/FEATURE-SPEC-auth.md (feature-spec)
  ✓ CLAUDE.md (project-overview)

Summary:
  Added 3 files, 8 episodes

Verbose Output¶

Graphiti Add Context

Connected to Graphiti

Parsing docs/architecture/ADR-001.md with adr
  Found 1 episodes
    - ADR-001 (adr)
  ✓ docs/architecture/ADR-001.md (adr)

Parsing docs/features/FEATURE-SPEC-auth.md with feature-spec
  Found 5 episodes
    - FEATURE-SPEC-auth (feature-spec)
    - TASK-AUTH-001 (task)
    - TASK-AUTH-002 (task)
    - TASK-AUTH-003 (task)
    - TASK-AUTH-004 (task)
  ✓ docs/features/FEATURE-SPEC-auth.md (feature-spec)

Summary:
  Added 2 files, 6 episodes

Dry Run Output¶

Graphiti Add Context

Connected to Graphiti

  ✓ docs/architecture/ADR-001.md (adr)
  ✓ docs/features/FEATURE-SPEC-auth.md (feature-spec)

Dry run complete - Would add:
  2 files, 6 episodes

Warnings and Errors¶

Warnings:
  Warning: docs/incomplete.md: Missing required section 'Decision'

Errors:
  Error: docs/invalid.md: Parse failed

Parser Auto-Detection¶

The command automatically detects the appropriate parser based on:

Filename patterns (primary):
ADR-*.md → ADR parser
FEATURE-SPEC-*.md, *-feature-spec.md → Feature spec parser
CLAUDE.md, README.md → Project overview parser
Other .md files → Project doc parser
Content structure (fallback):
Presence of ADR sections (Status, Context, Decision)
Feature spec structure (Tasks, Phases, Dependencies)
Project overview markers

Use --type to override auto-detection.

Supported Parser Types¶

Type	Description	Use `--type`
`adr`	Architecture Decision Records	`--type adr`
`feature-spec`	Feature specifications	`--type feature-spec`
`project-overview`	Project overview documents	`--type project-overview`
`project-doc`	General project documentation	`--type project-doc`

For detailed parser information, see Graphiti Parsers Guide.

Episodes Created¶

The command creates episodes in Graphiti based on the parser type:

ADR Parser¶

1 episode per ADR: Complete decision record
Group ID: {project}__project_decisions
Entity Type: adr
Metadata: Title, status, decision date

Feature Spec Parser¶

1 episode for spec: Feature overview
1 episode per task: Individual task details
Group ID: {project}__feature_specs
Entity Types: feature-spec, task
Metadata: Dependencies, priorities, phases

Project Overview Parser¶

1 episode: Project overview
Group ID: {project}__project_overview
Entity Type: project-overview
Metadata: Tech stack, architecture, purpose

Project Doc Parser¶

1 episode per document: General documentation
Group ID: {project}__project_docs
Entity Type: project-doc

When to Use add-context¶

Initial Project Setup¶

Add core project documentation to Graphiti:

# Add project overview
guardkit graphiti add-context CLAUDE.md

# Add all architecture decisions
guardkit graphiti add-context docs/architecture/ --pattern "ADR-*.md"

# Add all feature specs
guardkit graphiti add-context docs/features/ --pattern "FEATURE-SPEC-*.md"

After Creating New Documentation¶

Add newly created docs:

# New ADR
guardkit graphiti add-context docs/architecture/ADR-042-use-redis.md

# New feature spec
guardkit graphiti add-context docs/features/FEATURE-SPEC-notifications.md

After Updating Documentation¶

Update existing episodes with new content:

# ADR status changed (Proposed → Accepted)
guardkit graphiti add-context docs/architecture/ADR-023.md --force

# Feature spec updated with new tasks
guardkit graphiti add-context docs/features/FEATURE-SPEC-auth.md --force

Bulk Operations¶

Add multiple documents at once:

# All documentation
guardkit graphiti add-context docs/

# Only architecture docs
guardkit graphiti add-context docs/architecture/

# Specific pattern
guardkit graphiti add-context docs/ --pattern "**/design-*.md"

Best Practices¶

1. Preview First with --dry-run¶

Always preview before bulk operations:

guardkit graphiti add-context docs/ --dry-run

2. Use Specific Patterns¶

Narrow down to specific file types:

# Better
guardkit graphiti add-context docs/ --pattern "ADR-*.md"

# Instead of
guardkit graphiti add-context docs/

3. Use --force for Updates¶

When updating existing content, use --force:

guardkit graphiti add-context docs/ADR-001.md --force

4. Verify After Adding¶

Check that episodes were created:

guardkit graphiti add-context docs/ADR-001.md
guardkit graphiti verify --verbose

5. Use --verbose for Debugging¶

When troubleshooting parser detection:

guardkit graphiti add-context docs/ --verbose

Add related documents together:

# Add all ADRs
guardkit graphiti add-context docs/architecture/ --pattern "ADR-*.md"

# Then add all feature specs
guardkit graphiti add-context docs/features/ --pattern "FEATURE-SPEC-*.md"

Troubleshooting¶

File Not Detected by Parser¶

Symptom: "No parser found for: file.md (unsupported)"

Solution:

# Check file content structure
cat file.md

# Force specific parser
guardkit graphiti add-context file.md --type adr

# Or rename file to match pattern
mv file.md ADR-042-file.md

Parse Failed¶

Symptom: "Error: file.md: Parse failed"

Solution:

# Use verbose to see detailed error
guardkit graphiti add-context file.md --verbose

# Check for required sections (ADR: Status, Context, Decision)
# Check for valid YAML frontmatter

No Files Found¶

Symptom: "No files found matching pattern"

Solution:

# Check pattern syntax (glob patterns)
guardkit graphiti add-context docs/ --pattern "*.md"  # Only in docs/
guardkit graphiti add-context docs/ --pattern "**/*.md"  # Recursive

# Verify files exist
ls docs/*.md

Connection Failed¶

Symptom: "Graphiti connection failed or disabled"

Solution:

# Check Graphiti status
guardkit graphiti status

# Verify Neo4j is running
docker ps | grep neo4j

# Check configuration
cat ~/.guardkit/config.yaml

Episodes Not Searchable¶

Symptom: Episodes added but not found in searches

Solution:

# Wait for Graphiti indexing (can take 1-2 minutes)

# Verify episodes exist
guardkit graphiti verify --verbose

# Check group IDs in search queries

Advanced Usage¶

Custom Glob Patterns¶

# All markdown in specific subdirectories
guardkit graphiti add-context docs/ --pattern "{architecture,features}/**/*.md"

# Exclude certain files
guardkit graphiti add-context docs/ --pattern "**/!(README).md"

# Multiple patterns (run separately)
guardkit graphiti add-context docs/ --pattern "ADR-*.md"
guardkit graphiti add-context docs/ --pattern "FEATURE-*.md"

Automation Scripts¶

#!/bin/bash
# add-all-docs.sh

# Preview first
guardkit graphiti add-context docs/ --dry-run

# If preview looks good, add
if [ $? -eq 0 ]; then
  guardkit graphiti add-context docs/ --quiet
  echo "Documentation added to Graphiti"
fi

CI/CD Integration¶

# .github/workflows/update-graphiti.yml
name: Update Graphiti

on:
  push:
    paths:
      - 'docs/**/*.md'

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Add changed docs to Graphiti
        run: |
          guardkit graphiti add-context docs/ --force --quiet

guardkit graphiti add-context¶

Overview¶

Usage¶

Arguments¶

Options¶

Examples¶

Add a Single File¶

Add Multiple Files from Directory¶

Force Specific Parser¶

Preview Mode (Dry Run)¶

Verbose Output¶

Quiet Mode¶

Overwrite Existing Content¶

Output¶

Standard Output¶

Verbose Output¶

Dry Run Output¶

Warnings and Errors¶

Parser Auto-Detection¶

Supported Parser Types¶

Episodes Created¶

ADR Parser¶

Feature Spec Parser¶

Project Overview Parser¶

Project Doc Parser¶

When to Use add-context¶

Initial Project Setup¶

After Creating New Documentation¶

After Updating Documentation¶

Bulk Operations¶

Best Practices¶

1. Preview First with --dry-run¶

2. Use Specific Patterns¶

3. Use --force for Updates¶

4. Verify After Adding¶

5. Use --verbose for Debugging¶

6. Group Related Additions¶

Troubleshooting¶

File Not Detected by Parser¶

Parse Failed¶

No Files Found¶

Connection Failed¶

Episodes Not Searchable¶

Advanced Usage¶

Custom Glob Patterns¶

Automation Scripts¶

CI/CD Integration¶

See Also¶