gyrus 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evgenii Khramkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,273 @@
+# Gyrus
+
+[![CI](https://github.com/evgenii-polyakun/gyrus/actions/workflows/ci.yml/badge.svg)](https://github.com/evgenii-polyakun/gyrus/actions/workflows/ci.yml)
+[![Release](https://github.com/evgenii-polyakun/gyrus/actions/workflows/release.yml/badge.svg)](https://github.com/evgenii-polyakun/gyrus/actions/workflows/release.yml)
+[![npm version](https://img.shields.io/npm/v/gyrus.svg)](https://www.npmjs.com/package/gyrus)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Bun](https://img.shields.io/badge/Bun-%3E%3D1.0.0-black)](https://bun.sh)
+
+**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
+
+```bash
+# Clone the repository
+git clone https://github.com/evgenii-polyakun/gyrus.git
+cd gyrus
+
+# Install dependencies
+bun install
+
+# Build (optional - for standalone binary)
+bun run build
+```
+
+### First-Time Setup
+
+```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
+
+### Adding More Workspaces
+
+```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 <name>` | Set the default workspace |
+| `gyrus doctor` | Run diagnostics and health check |
+| `gyrus mcp` | Start the MCP server (stdio) |
+| `gyrus serve` | Start the dashboard server (coming soon) |
+| `gyrus daemon` | Start HTTP/SSE MCP server (coming soon) |
+
+### Command Options
+
+```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
+```
+
+## MCP Integration
+
+### Claude Desktop Configuration
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "gyrus": {
+      "command": "bun",
+      "args": ["run", "/path/to/gyrus/src/index.ts", "mcp"]
+    }
+  }
+}
+```
+
+Or using the compiled binary:
+
+```json
+{
+  "mcpServers": {
+    "gyrus": {
+      "command": "/path/to/gyrus/dist/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`:
+
+```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](https://bun.sh)
+- **Language**: TypeScript
+- **MCP SDK**: [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk)
+- **Frontmatter**: [gray-matter](https://github.com/jonschlinkert/gray-matter)
+- **Validation**: [Zod](https://zod.dev)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "gyrus",
+  "version": "0.1.0",
+  "description": "Model-agnostic knowledge management CLI with MCP server support",
+  "type": "module",
+  "bin": {
+    "gyrus": "./src/index.ts"
+  },
+  "main": "./src/index.ts",
+  "files": [
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "tsconfig.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "dev": "bun --watch run src/index.ts",
+    "build": "bun build src/index.ts --compile --outfile dist/gyrus",
+    "build:all": "bun run build:macos && bun run build:linux",
+    "build:macos": "bun build src/index.ts --compile --target=bun-darwin-arm64 --outfile dist/gyrus-darwin-arm64 && bun build src/index.ts --compile --target=bun-darwin-x64 --outfile dist/gyrus-darwin-x64",
+    "build:linux": "bun build src/index.ts --compile --target=bun-linux-x64 --outfile dist/gyrus-linux-x64 && bun build src/index.ts --compile --target=bun-linux-arm64 --outfile dist/gyrus-linux-arm64",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "doctor": "bun run src/index.ts doctor",
+    "mcp": "bun run src/index.ts mcp",
+    "prepublishOnly": "bun run typecheck && bun run test"
+  },
+  "keywords": [
+    "knowledge-management",
+    "mcp",
+    "model-context-protocol",
+    "cli",
+    "ai",
+    "notes",
+    "adr",
+    "architecture-decision-records",
+    "brain",
+    "second-brain",
+    "pkm",
+    "personal-knowledge-management"
+  ],
+  "author": "Evgenii Polikutin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/evgenii-polyakun/gyrus.git"
+  },
+  "bugs": {
+    "url": "https://github.com/evgenii-polyakun/gyrus/issues"
+  },
+  "homepage": "https://github.com/evgenii-polyakun/gyrus#readme",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "gray-matter": "^4.0.3",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "prettier": "^3.8.0",
+    "typescript": "^5",
+    "vitest": "^4.0.17"
+  }
+}