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

$3

``bash


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
`

$3

`bash


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

$3

`bash


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 | 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 | Generate shell completions (bash, zsh, fish) |
| gyrus serve | Start the dashboard server (coming soon) |
| gyrus daemon | Start HTTP/SSE MCP server (coming soon) |

$3

`bash


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.

$3

`bash


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
`

$3

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

`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 |

$3

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.

$3

Add to your ~/.bashrc:

`bash
eval "$(gyrus completions bash)"
`

Or save to completion directory:

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

$3

Add to your ~/.zshrc:

`bash
eval "$(gyrus completions zsh)"
`

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

`bash
mkdir -p ~/.zsh/completions
gyrus completions zsh > ~/.zsh/completions/_gyrus


Add to ~/.zshrc: fpath=(~/.zsh/completions $fpath)


`

$3

Save to fish completions directory:

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

MCP Integration

$3

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

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

Or using the compiled binary:

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

$3

#### 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

$3

`
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:

`
/
├── 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:

`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

`bash


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:

`markdown
---
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:

`markdown
---
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