Studiograph

Team-based AI agent platform with Git-backed knowledge graphs. Studiograph helps creative services teams capture operational knowledge as Markdown entities with YAML frontmatter, organized into Git repositories, and enables AI agents to produce work reflecting real team context.

Quick Start

Prerequisites

• Node.js 20+
• Git installed and configured
• An API key from a supported LLM provider (Anthropic, OpenAI, Google, xAI, Groq, or OpenRouter)
• Supported platforms: macOS (Apple Silicon), Linux (x64/arm64), Windows (x64/arm64). Intel Macs are not supported due to a LanceDB dependency.

Install

npm install -g studiograph

Create a Workspace

studiograph init "My Studio"

This creates a workspace directory with a .studiograph/ config folder — similar to how Git uses .git/ — and scaffolds example entities to get you started.

To create repos on GitHub during init:

studiograph init "My Studio" --github --github-org my-org

Join an Existing Workspace

studiograph join https://github.com/my-org/.studiograph.git

This clones the config repo, identifies your role from the team roster, and clones all repos you have access to.

Start the Agent

cd my-studio
studiograph start

On first run, you'll be prompted to select an AI provider and model. The agent provides a chat interface where you can create, search, and manage entities across your knowledge graph.

How It Works

Workspace Structure

A Studiograph workspace is a directory containing a .studiograph/ configuration folder and one or more content repositories:

my-studio/
├── .studiograph/           # Config repo (workspace.json, team roster, migrations)
├── acme-rebrand/           # Collection (client project)
├── website-redesign/       # Collection (another project)
├── team-knowledge/         # Collection (processes, standards)
└── private/                # Local-only, gitignored

Collections

Each subdirectory is a collection — a Git repo containing related entities. Collections are lightweight and flexible: one per project, one for team knowledge, one for business operations, or however your team thinks.

Entities

Entities are Markdown files with YAML frontmatter, stored in type-based directories within repos:

acme-rebrand/
├── project/
│   └── acme-rebrand.md
├── meeting/
│   └── kickoff-2024-01-15.md
├── deliverable/
│   └── brand-guidelines-v1.md
└── person/
    └── jane-doe.md

Each entity file looks like:

---
entity_type: project
entity_id: acme-rebrand
name: "Acme Rebrand"
status: active
team:
  - [[alice-smith]]
  - [[bob-jones]]
related_projects:
  - [[website-redesign]]
created_at: 2024-01-15T10:00:00Z
updated_at: 2024-02-20T14:30:00Z
created_by: alice
updated_by: alice
---

# Acme Rebrand

Project notes and context go here...

Entity IDs are always kebab-case. Entities link to each other with wikilinks ([[entity-id]]), which work across repos.

There are 17 built-in entity types (project, meeting, person, organization, decision, task, document, etc.), and workspaces can define custom types via schema_extensions in workspace.json.

CLI Commands

Getting Started

Daily Workflow

Workspace Management

Server & Deployment

Integrations

Integrations

Claude Desktop & Claude Code (MCP)

Studiograph exposes a Model Context Protocol server so any MCP client can read and write your knowledge graph directly.

Claude Desktop — add to your config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "studiograph": {
      "command": "studiograph",
      "args": ["mcp", "/absolute/path/to/your/workspace"]
    }
  }
}

Claude Code — add to your project's .mcp.json:

{
  "mcpServers": {
    "studiograph": {
      "command": "studiograph",
      "args": ["mcp", "/absolute/path/to/your/workspace"]
    }
  }
}

If you're running from the workspace directory, you can omit the path: studiograph mcp.

MCP tools available: list_repos, list_entities, get_entity, search_entities, create_entity, update_entity, delete_entity.

Third-Party Connectors

Studiograph can connect to external services via MCP connectors. Built-in connector configs are available for:

• Linear — issues and project tracking
• Slack — messages and channels
• Figma — design files
• Google Workspace — docs, sheets, calendar
• Granola — meeting notes
• Pipedrive — CRM deals and contacts

Configure with:

studiograph connector add linear

Connector credentials are stored at ~/.studiograph/connectors/ with restricted file permissions.

HTTP Server

studiograph serve starts a Fastify server with:

Authentication uses bearer tokens set via the API_KEYS environment variable (semicolon-separated). When no keys are configured, the server runs in open dev mode.

Deployment

Railway

studiograph deploy railway

The guided wizard walks through setup. Required environment variables:

On first boot, the server clones the config repo and all content repos automatically.

Development

Setup

git clone <repo-url>
cd studiograph
npm install
npm run build

Scripts

npm run build     # Compile TypeScript + copy prompt/skill files to dist/
npm run dev       # Watch mode (tsc --watch)
npm run test      # Run tests in watch mode (Vitest)
npm run lint      # ESLint
npx vitest run    # Run tests once (CI mode)

Run a Single Test

npx vitest run src/core/__tests__/graph.test.ts

Project Layout

src/
├── cli/           # Commander.js commands
├── core/          # Workspace, graph, validation, schema registry, types
├── services/      # Git, Markdown, CSV, vector search, assets, memory, lint
├── agent/         # AI orchestrator, tools, skills, system prompts
├── server/        # Fastify HTTP server and API routes
├── mcp/           # Model Context Protocol server and connector manager
├── auth/          # GitHub authentication (OAuth device flow)
└── utils/         # Preflight checks, version checking, git helpers

Key Files

• src/core/types.ts — Zod schemas for workspace config, entities, repos
• src/core/validation.ts — All 17 built-in entity type schemas
• src/core/graph.ts — BaseGraphManager (CRUD for a single repo)
• src/core/workspace-manager.ts — WorkspaceManager (multi-repo coordination)
• src/core/workspace.ts — .studiograph/ directory management
• src/agent/orchestrator.ts — AI agent setup with multi-provider support
• src/server/index.ts — Fastify server factory

License

Apache 2.0 — see LICENSE for details.