Gyrus

Model-agnostic knowledge management CLI with MCP server support.

Gyrus is a unified CLI tool for managing knowledge notes and Architecture Decision Records (ADRs) across multiple workspaces. It works with any AI agent, IDE, or workflow through the Model Context Protocol (MCP).

A gyrus is a ridge on the cerebral cortex — the folds that increase surface area for neural connections. Like a gyrus, this tool connects different regions (agents, IDEs, models) and processes signals regardless of source.

Features

• 🧠 Multi-Workspace Support — Manage separate knowledge bases for personal, work, and project contexts
• 🔌 MCP Server — Expose knowledge and ADR tools to AI agents via stdio transport
• 📚 Knowledge Notes — Structured markdown notes with YAML frontmatter
• 📋 ADR System — Architecture Decision Records for spec-driven development
• ⚡ Fast — Built with Bun for instant startup

Quick Start

Installation

# Clone the repository
git clone https://github.com/ewgenius/gyrus.git
cd gyrus

# Install dependencies
bun install

# Build (optional - for standalone binary)
bun run build

First-Time Setup

# Initialize your first workspace at ~/gyrus
gyrus init

# Or specify a custom path and name
gyrus init ~/my-brain --name personal --description "Personal knowledge"

This creates:

• Config file at ~/.config/gyrus/config.json
• Default workspace at ~/gyrus with knowledge and ADR folders

Adding More Workspaces

# Add a work workspace
gyrus init ~/work/brain --name work --description "Work projects"

# Add a project-specific workspace
gyrus init ./brain --name myproject --description "Project notes"

# List all workspaces
gyrus workspaces    # or: gyrus ws

# Switch default workspace
gyrus use work

Commands

| Command | Description | |---------|-------------| | gyrus init [path] | Initialize a new workspace | | gyrus workspaces | List all registered workspaces (alias: ws) | | gyrus use <name> | Set the default workspace | | gyrus doctor | Run diagnostics and health check | | gyrus mcp | Start the MCP server (stdio) | | gyrus sync | Stage and commit all changes to git | | gyrus push | Push commits to remote | | gyrus pull | Pull latest from remote | | gyrus completions <shell> | Generate shell completions (bash, zsh, fish) | | gyrus serve | Start the dashboard server (coming soon) | | gyrus daemon | Start HTTP/SSE MCP server (coming soon) |

Command Options

# Initialize with custom name and description
gyrus init ~/path --name work --description "Work projects"

# Run MCP server for specific workspace
gyrus mcp --workspace work

# Check specific workspace health
gyrus doctor --workspace work

# Check all workspaces
gyrus doctor --all

Git Sync

Gyrus integrates with git to backup and sync your knowledge across machines.

Commands

# Stage and commit all changes
gyrus sync

# Commit with custom message
gyrus sync -m "Add authentication patterns"

# Sync and push in one command
gyrus sync --push

# Push committed changes
gyrus push

# Pull latest changes
gyrus pull

# Pull with auto-stash (saves local changes, pulls, restores)
gyrus pull --stash

# Sync all workspaces at once
gyrus sync --all
gyrus push --all
gyrus pull --all

# Preview what would be committed
gyrus sync --dry-run

# Verbose output
gyrus sync -v

Configuration

Add git settings to workspace config in ~/.config/gyrus/config.json:

{
  "workspaces": [
    {
      "name": "personal",
      "path": "~/gyrus",
      "description": "Personal knowledge",
      "git": {
        "enabled": true,
        "autoSync": false,
        "autoPush": false,
        "commitPrefix": "gyrus:",
        "defaultBranch": "main"
      }
    }
  ]
}

| Setting | Default | Description | |---------|---------|-------------| | enabled | true | Enable git integration (auto-detected if .git exists) | | autoSync | false | Auto-commit after create/update operations | | autoPush | false | Auto-push after sync | | commitPrefix | "gyrus:" | Prefix for auto-generated commit messages | | defaultBranch | "main" | Default branch for operations |

Auto-Generated Commit Messages

When you run gyrus sync without a message, it generates:

gyrus: sync knowledge and ADRs - 2026-01-15 15:30

Shell Completions

Gyrus provides shell completions for bash, zsh, and fish.

Bash

Add to your ~/.bashrc:

eval "$(gyrus completions bash)"

Or save to completion directory:

gyrus completions bash > ~/.local/share/bash-completion/completions/gyrus

Zsh

Add to your ~/.zshrc:

eval "$(gyrus completions zsh)"

Or save to completions directory (ensure the directory is in your fpath):

mkdir -p ~/.zsh/completions
gyrus completions zsh > ~/.zsh/completions/_gyrus
# Add to ~/.zshrc: fpath=(~/.zsh/completions $fpath)

Fish

Save to fish completions directory:

gyrus completions fish > ~/.config/fish/completions/gyrus.fish

MCP Integration

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gyrus": {
      "command": "gyrus",
      "args": ["mcp"]
    }
  }
}

Or using the compiled binary:

{
  "mcpServers": {
    "gyrus": {
      "command": "gyrus",
      "args": ["mcp"]
    }
  }
}

Available MCP Tools

Workspace Tools

• gyrus_list — List all registered workspaces
• gyrus_switch — Switch active workspace for the session

Knowledge Tools

• knowledge_list — List notes with optional filtering
• knowledge_read — Read a note by ID or path
• knowledge_search — Search notes by query, tags, or category
• knowledge_create — Create a new note
• knowledge_update — Update an existing note

ADR Tools

• adr_list — List ADRs with optional filtering
• adr_read — Read an ADR by name
• adr_search — Search ADRs by query, status, type, or tags
• adr_create — Create a new ADR
• adr_update — Update an existing ADR

Example Agent Workflow

Agent: Let me check what workspaces are available.
[calls gyrus_list]

Agent: I see you have personal and work workspaces.
       Which should I use for this task?

User: Use work, this is for my job.

Agent: Switching to work workspace.
[calls gyrus_switch with name="work"]

Agent: Now searching for relevant knowledge...
[calls knowledge_search with query="authentication"]

Workspace Structure

When you run gyrus init, it creates:

<workspace>/
├── 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
└── adrs/
    └── template.md         # ADR template

Configuration

Global config is stored at ~/.config/gyrus/config.json:

{
  "version": 1,
  "default": "personal",
  "workspaces": [
    {
      "name": "personal",
      "path": "~/gyrus",
      "description": "Personal knowledge and projects"
    },
    {
      "name": "work",
      "path": "~/work/brain",
      "description": "Work projects"
    }
  ],
  "settings": {
    "serve": { "port": 3333 },
    "daemon": { "port": 3334 }
  }
}

Development

# Run in development mode (auto-reload)
bun run dev

# Type checking
bun run typecheck

# Run doctor diagnostics
bun run doctor

# Build standalone binary
bun run build

Note Format

Knowledge notes use YAML frontmatter:

---
id: pattern-example
title: Example Pattern
created: 2026-01-15
updated: 2026-01-15
tags: [example, pattern]
related: [other-note-id]
---

# Content starts here

ADR Format

ADRs use this frontmatter:

---
title: Feature Name
description: Brief description
date_created: 2026-01-15
date_updated: 2026-01-15
status: todo | in-progress | in-review | blocked | completed | deprecated
type: enhancement | debug | research
tags: [optional, tags]
working_folder: /path/to/project
---

# Content starts here

Tech Stack

• Runtime: Bun
• Language: TypeScript
• MCP SDK: @modelcontextprotocol/sdk
• Frontmatter: gray-matter
• Validation: Zod

License

MIT