Introduction

Gyrus is a knowledge management system that gives AI coding assistants persistent memory. It provides structured storage for knowledge notes and Architecture Decision Records (ADRs), accessible via MCP (Model Context Protocol).

A gyrus is a ridge on the cerebral cortex — the folds that increase surface area for neural connections. Like a gyrus, this tool connects and persists information across sessions and tools.

The Problem: AI Assistants Have No Memory

Every time you start a new session with an AI assistant, it starts from zero:

• "Why did we choose this architecture?" — forgotten
• "What gotchas did we discover last week?" — forgotten
• "What patterns work well in this codebase?" — forgotten

You end up repeating context, re-explaining decisions, and watching the AI make the same mistakes you've already corrected.

The Solution: Persistent, Structured Memory

Gyrus solves this by providing a structured knowledge layer that AI assistants can read and write to:

Session 1: You discover a gotcha → AI saves it to Gyrus
Session 2: AI reads the gotcha → Avoids the same mistake

It's not just storage — it's organized storage. Gyrus uses an opinionated structure so you don't have to think about where things go.

Core Concepts

Workspaces

A workspace is a scoped container for your knowledge. Each workspace has its own notes, ADRs, and skills, stored in a simple directory structure:

workspace/
├── knowledge/     # Your notes
│   ├── projects/  # Project-specific context
│   ├── patterns/  # Reusable solutions
│   ├── tools/     # Tool configs and tips
│   ├── gotchas/   # Traps to avoid
│   └── decisions/ # Past decisions
├── adrs/          # Architecture Decision Records
└── skills/        # Reusable AI instructions

Why multiple workspaces? Different contexts need different knowledge:

• Personal — Your learning, side projects, general notes
• Work — Company-specific knowledge, team conventions
• Per-project — Notes that live with the codebase

When you switch projects, switch workspaces. The AI gets the right context automatically.

Knowledge Notes

Knowledge notes are markdown files with YAML frontmatter. They capture information worth remembering:

Category	What goes here
projects	Project architecture, setup notes, conventions
patterns	Solutions that work — code patterns, workflows
tools	Tool configs, useful commands, integration tips
gotchas	Things that tripped you up (so you don't repeat them)
decisions	Why you chose X over Y

Notes are tagged, searchable, and cross-referenced. When you ask the AI about something, it can search your knowledge first.

Architecture Decision Records (ADRs)

An ADR tracks a significant piece of work from start to finish:

## Goal

What you want to achieve

## Context

Background and constraints

## Proposed Solution

The approach you're taking

## Execution Plan

- [ ] Step 1
- [ ] Step 2

## Consequences

Trade-offs and outcomes

ADRs have status (todo → in-progress → completed) and type (enhancement, debug, research).

Why ADRs?

• They give structure to complex tasks
• The AI knows what you're working on and what's done
• You have a record of what was decided and why

Skills

A skill is a reusable set of instructions that an AI agent can load on demand:

---
name: code-review
title: Code Review Guide
triggers: [/code-review, /review]
tags: [quality, review]
---

When reviewing code, follow these guidelines...

Skills are different from knowledge notes:

• Knowledge notes capture what to remember
• Skills capture how to do things

Use skills for consistent processes like code review, testing strategies, or coding conventions.

The Workflow

Here's how Gyrus fits into your development:

1. Start a session → AI reads relevant knowledge from your workspace
2. Work on a task → Create an ADR to track progress, update as you go
3. Learn something → Save it as a knowledge note
4. Next session → AI has full context from day one

No more "let me explain the codebase again." No more "we tried that, it didn't work."

Opinionated by Design

Gyrus makes decisions so you don't have to:

• Pre-defined categories — No "where should I put this?"
• Consistent structure — Everything is easy to find
• Templates — Capture the right information every time
• Auto-maintained indexes — Stays organized automatically

Less friction means you'll actually use it.

Next Steps

• Installation — Get Gyrus set up
• Getting Started — Initialize your first workspace
• MCP Integration — Connect to your AI tools
• Skills — Create reusable AI instructions