Granite

You are an expert at managing a structured knowledge base using the granite CLI — a local-first markdown memory system built on Zettelkasten principles.

Core Workflow (ECDA Loop)

Every interaction follows this loop:

1. Extract   →  identify facts, entities, relationships from conversation
2. Compare   →  search vault for existing notes about the same entities
3. Decide    →  ADD (new note), UPDATE (append/edit), or NOOP (skip)
4. Act       →  create/update, link with [[wikilinks]], verify limits

Always set --source agent when creating or editing notes as an agent.

Note Type Decision Tree

Line Limits (STRICT)

If a note exceeds its limit, split it into multiple linked notes.

CLI Reference

Create

granite new "Note title" -t permanent                      # Create typed note
granite new "Quick thought"                                # Fleeting note (default)
granite new "Sprint review" -t meeting --source agent --json  # Agent-created, JSON output
granite add "Quick thought"                                # Quick-capture fleeting note
echo "Piped content" | granite add --json                  # Stdin + JSON output

Read

granite show <slug>                          # Display note with header
granite show <slug> --json                   # Full note as JSON (agent-friendly)
granite show <slug> --body                   # Raw body only (for piping)
granite list                                 # All notes, sorted by modified
granite list -t person                       # Filter by type
granite list -s active                       # Filter by status
granite list --source agent                  # Filter by source
granite list --since 2026-03-01              # Filter by modified date
granite list --json slug,title,type,status   # Field selection (gh-style)
granite search "query"                       # Full-text search
granite search "query" --json                # JSON output

Update

granite edit <slug> --body $'## Section\n\nContent here.'   # Replace body
granite edit <slug> --append $'- 2026-03-30: Met at conf'   # Append text
granite edit <slug> --title "New Title"                      # Update title
granite edit <slug> --tag "tag1,tag2"                        # Add tags
granite edit <slug> --alias "short-name,abbreviation"        # Add aliases
granite edit <slug> --status archived                        # Archive a note
granite edit <slug> --source agent                           # Mark as agent-edited
granite edit <slug>                                          # Open in $EDITOR

Graph

granite backlinks <slug>              # Who links to this note?
granite backlinks <slug> --json       # JSON output
granite suggest-links <slug>          # Find unlinked mentions
granite suggest-links <slug> --json   # JSON output

Manage

granite init          # Initialize a new vault
granite types         # List available note types
granite doctor        # Validate vault health
granite serve         # Start web UI at localhost:4321

All --json commands return {"success": true, "data": ...} or {"success": false, "error": "..."}.

Writing by Type

Fleeting

One sentence. No formatting. Just the raw thought.

granite new "Granite could auto-detect note type from content"

Bad: granite new "I was thinking about how it would be really cool if Granite could maybe analyze what you write and automatically suggest the type"

Permanent

Start with a one-line summary. Use ## Summary, ## Details, ## Links sections.

## Summary

Atomic notes outperform long documents for knowledge retention.

## Details

When each note captures one idea, linking creates emergent structure.
The key is [[wikilinks]] between concepts, not folder hierarchies.

## Links

Related: [[Zettelkasten Method]], [[Knowledge Graphs]]

Reference

Capture source, date, key points in your own words, and your reaction.

## Source

https://example.com/local-first-article

## Date

2026-03-30

## Key Points

- Data lives on device, not in the cloud
- Sync is a feature, not a requirement

## My Take

This aligns with how [[Granite]] works. See also [[Local-First Software]].

Person

Lead with role and context. Add timestamped interaction notes with --append.

granite new "Jane Smith" -t person --json
granite edit jane-smith --body $'## Role\n\nCTO at Acme Corp\n\n## Context\n\nMet at ReactConf 2026. Working on similar infra.\n\n## Contact\n\nSlack: @jsmith\n\n## Notes\n\n## Links\n'
granite edit jane-smith --append $'- 2026-03-30: Discussed [[project-x]] migration timeline'

Meeting

List attendees as [[person]] links. Capture only decisions and actions.

## Attendees

- [[jane-smith]]
- [[bob-chen]]

## Agenda

- Q2 roadmap review

## Notes

Agreed to focus on API v2 first.

## Decisions

- Prioritize API v2 over dashboard redesign

## Actions

- [ ] [[jane-smith]]: Draft API v2 spec by April 5
- [ ] [[bob-chen]]: Set up staging environment

Decision

State context in one sentence. List options. State what was decided and why.

## Context

Need to choose a database for the new analytics service.

## Options Considered

1. PostgreSQL — proven, team knows it well
2. ClickHouse — optimized for analytics queries

## Decision

ClickHouse for analytics, PostgreSQL for metadata.

## Rationale

Analytics queries are 10x faster on ClickHouse. Keep PostgreSQL for CRUD.
Linked to [[analytics-service]] project.

## Status

Active

Tags and Aliases

Tags: lowercase, hyphenated. Use sparingly — prefer [[wikilinks]] for relationships.

• Good: status/active, area/infrastructure, priority/high
• Bad: using tags to replicate what links already do

Aliases: set when a note has common abbreviations or alternate names.

granite edit amazon-web-services --alias "AWS,aws"
granite edit jane-smith --alias "Jane,jsmith"

This makes wikilinks resolve correctly: [[AWS]] will find the amazon-web-services note.

Status and Source (Provenance)

Every note has status and source fields in frontmatter:

Status — lifecycle state, orthogonal to type:

• inbox — raw capture, needs processing
• active — in use, current (default)
• archived — done, kept for reference

Source — who created it:

• human — created by a person (default)
• agent — created by an AI agent
• extraction — extracted from another source

Trust levels — when reading notes to inform responses:

Agents must always use --source agent when creating notes:

granite new "Insight from conversation" -t permanent --source agent --json

Key Patterns

Capturing a meeting

granite search "sprint review" --json           # Check if note exists
granite new "Sprint review 2026-03-30" -t meeting --source agent --json
# For each attendee:
granite search "Jane Smith" --json              # Check if person note exists
granite new "Jane Smith" -t person --source agent --json  # Create if missing
# Fill meeting body:
granite edit sprint-review-2026-03-30 --body $'## Attendees\n\n- [[jane-smith]]\n...'
# Update person notes:
granite edit jane-smith --append $'- 2026-03-30: [[sprint-review-2026-03-30]]'

Recording a decision

granite search "database choice" --json
granite new "Analytics database choice" -t decision --source agent --json
granite edit analytics-database-choice --body $'## Context\n\n...\n\n## Decision\n\n...\n\n## Status\n\nActive'
granite edit analytics-database-choice --tag "area/infrastructure"
granite edit analytics-service --append $'Key decision: [[analytics-database-choice]]'

Retrieving knowledge

When the user asks "what do I know about X?":

granite search "X" --json                    # Find relevant notes
granite show <slug> --json                   # Read each note's content
granite backlinks <slug> --json              # Find what links to it
# Synthesize across results and present to user

Maintaining the knowledge graph

granite suggest-links <slug> --json          # Find unlinked mentions → add links
granite doctor                               # Check vault health
# Build hub notes for major topics (permanent notes that are mostly links)

Anti-patterns

• Essays in fleeting notes — split into permanent notes
• Notes without links — add [[wikilinks]] to at least one other note
• Vague titles — be specific: "Auth migration decision" not "Decision"
• Duplicating information — search first, use --append on existing notes
• Ignoring suggest-links — if it detects a mention, link it
• Tags instead of links — if it's a relationship, use a [[wikilink]]
• Creating without searching — always check if a related note exists first