Knowledge Notes

Knowledge notes are structured markdown files for capturing information that persists across sessions and tools. They're designed to be both human-readable and AI-accessible.

Overview

Notes are organized into categories within your workspace's knowledge/ directory:

knowledge/
├── README.md           # Knowledge system guide
├── index.md            # Master index of notes
├── instructions.md     # AI agent instructions
├── projects/           # Project-specific knowledge
├── patterns/           # Reusable patterns
├── tools/              # Tool and tech notes
├── gotchas/            # Common pitfalls
└── decisions/          # Key decisions

Note Format

Each note uses YAML frontmatter followed by markdown content:

---
id: pattern-retry-with-backoff
title: Retry with Exponential Backoff
created: 2025-01-15
updated: 2025-01-15
tags: [patterns, reliability, networking]
related: [tool-axios, gotcha-rate-limits]
---

# Retry with Exponential Backoff

When making network requests, implement retry logic with exponential backoff...

Frontmatter Fields

Field	Required	Description
id	Yes	Unique identifier in kebab-case
title	Yes	Human-readable title
created	Yes	Creation date (YYYY-MM-DD)
updated	Yes	Last update date (auto-updated)
tags	No	Array of tags for categorization
related	No	IDs of related notes for cross-referencing
description	No	Brief description of the note

Categories

Projects

Project-specific knowledge that doesn't belong in the codebase itself:

• Architecture overviews
• Environment setup notes
• Team conventions
• External service integrations

Patterns

Reusable solutions you've found effective:

• Code patterns
• Architectural patterns
• Process patterns
• Communication patterns

Tools

Notes about tools and technologies you use:

• Configuration snippets
• Useful commands
• Integration tips
• Version-specific notes

Gotchas

Things that have tripped you up before:

• Common mistakes
• Unintuitive behavior
• Edge cases
• Compatibility issues

Decisions

Important decisions and their rationale:

• Technology choices
• Architecture decisions
• Process decisions

TIP

For formal decision tracking with status management, use ADRs instead.

Working with Notes via CLI

List Notes

# List all notes
gyrus knowledge list

# Filter by category
gyrus knowledge list --category patterns

# Filter by tags
gyrus knowledge list --tags reliability,networking

Read Notes

# Read by ID
gyrus knowledge read pattern-retry-with-backoff

# Read by path
gyrus knowledge read patterns/pattern-retry-with-backoff.md

Search Notes

# Search by text
gyrus knowledge search "exponential backoff"

# Search with filters
gyrus knowledge search "retry" --category patterns --tags networking

Working with Notes via MCP

AI agents can interact with your knowledge through MCP tools:

knowledge_list

List notes with optional filtering:

{
  "category": "patterns",
  "tags": ["reliability"]
}

knowledge_read

Read a specific note:

{
  "id": "pattern-retry-with-backoff"
}

knowledge_search

Search across notes:

{
  "query": "exponential backoff",
  "category": "patterns"
}

knowledge_create

Create a new note:

{
  "id": "pattern-circuit-breaker",
  "title": "Circuit Breaker Pattern",
  "category": "patterns",
  "content": "# Circuit Breaker Pattern\n\nPrevent cascading failures...",
  "tags": ["patterns", "reliability"]
}

knowledge_update

Update an existing note:

{
  "id": "pattern-retry-with-backoff",
  "content": "# Updated content...",
  "tags": ["patterns", "reliability", "networking"]
}

Best Practices

Keep Notes Focused

Each note should cover a single topic. If a note grows too large, split it into related notes and use the related field to link them.

Use Consistent IDs

Follow a naming convention for IDs:

• pattern-<name> for patterns
• tool-<name> for tools
• gotcha-<name> for gotchas
• project-<name> for projects
• decision-<name> for decisions

Tag Strategically

Use tags to create cross-cutting categories:

• Technology tags: typescript, python, docker
• Domain tags: authentication, payments, analytics
• Quality tags: reliability, performance, security

Link Related Notes

Use the related field to create a knowledge graph:

related: [pattern-circuit-breaker, gotcha-timeout-defaults]

Keep Notes Updated

When you learn something new about a topic, update the existing note rather than creating a new one. The updated date tracks when notes were last modified.

Next Steps

• Skills — Reusable AI instructions
• Architecture Decision Records — Track formal decisions
• MCP Integration — Connect to AI agents
• Commands Reference — Full CLI documentation