Model-agnostic knowledge management CLI with MCP server support
npm install 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.
- š§ 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
``bashClone the repository
git clone https://github.com/ewgenius/gyrus.git
cd gyrus
$3
`bash
Initialize your first workspace at ~/gyrus
gyrus initOr 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 wsSwitch 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 workCheck specific workspace health
gyrus doctor --workspace workCheck 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 syncCommit with custom message
gyrus sync -m "Add authentication patterns"Sync and push in one command
gyrus sync --pushPush committed changes
gyrus pushPull latest changes
gyrus pullPull with auto-stash (saves local changes, pulls, restores)
gyrus pull --stashSync all workspaces at once
gyrus sync --all
gyrus push --all
gyrus pull --allPreview what would be committed
gyrus sync --dry-runVerbose 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 devType checking
bun run typecheckRun doctor diagnostics
bun run doctorBuild 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
``- Runtime: Bun
- Language: TypeScript
- MCP SDK: @modelcontextprotocol/sdk
- Frontmatter: gray-matter
- Validation: Zod
MIT