Factsets

Package
CI/CD

A self-maintaining knowledge base for AI agents, exposed via the Model Context Protocol (MCP). Manages facts (atomic knowledge), resources (cached external content), skills (procedural markdown), and execution logs (command history) using SQLite.

Features

• Persistent Context - Knowledge survives across sessions
• Self-Maintaining - Staleness detection with refresh instructions
• Tag-Based Organization - Flexible categorization and retrieval
• Skill Documents - Markdown files for procedural knowledge
• User Preferences - Configurable output style and agent behavior
• MCP Protocol - Standard interface for AI tool/prompt definitions

Installation

npm install --global factsets
pnpm install --global factsets
bun install --global factsets

Quick Start

As MCP Server

Add to your MCP client configuration (Claude Desktop, GitHub Copilot, Cursor, etc.), using bunx, npx or pnpm dlx accordingly:

{
  "mcpServers": {
    "factsets": {
      "command": "bunx",
      "args": ["factsets", "mcp-server"]
    }
  }
}

Or run directly:

bunx factsets mcp-server

First-Time Setup

After adding Factsets to your MCP client, run the setup prompt to integrate it into your project:

In a supported IDE: Type /mcp.factsets.setup in the chat to run the guided setup

In other clients: Call the get_setup_guide tool or use the setup prompt

The setup guide will:

• Analyze your project structure and establish baseline facts
• Configure the skills directory for your AI client
• Create or update AGENTS.md with Factsets instructions
• Migrate any existing skills with Factsets integration
• Register key configuration files as resources

This one-time setup ensures agents have full context on every future interaction.

CLI Commands

# Start MCP server (default command - auto-watches skill files and seeds starter content)
bunx factsets [--database-url <path>] [--client <type>]

# Explicit mcp-server command (same as above)
bunx factsets mcp-server [--database-url <path>] [--client <type>]

# Start without file watching
bunx factsets --no-watch-skills

# Start without seeding starter content
bunx factsets --no-seed

# Run file watcher standalone
bunx factsets watch-files [--database-url <path>]

# Run background maintenance worker
bunx factsets worker [--database-url <path>]

# Export database to JSON
bunx factsets dump backup.json

# Restore database from JSON
bunx factsets restore backup.json

The --client flag configures where skill files are stored (e.g., github-copilot -> .github/prompts/skills/). If you want to change clients / your skill directory, do so through your agent which will migrate skills for you.

See Configuration Guide for all options.

Core Concepts

MCP Tools

Facts

Resources

Skills

Execution Logs

Tags

Configuration

User Preferences

Maintenance

Context & Guides

MCP Prompts

Documentation

• Configuration Guide - CLI flags, client setup, and skills directory
• Design Reference - Full API documentation
• Concept - Philosophy and design rationale
• Agent Workflow - How agents use Factsets

Development

# Run tests
bun test

# Run full e2e (tests + build + dry run)
bun e2e

# Build distribution
bun dist

# Format code
bun format

# Lint
bun lint

# Generate database migrations
bun migrations

# Inspect MCP server with inspector
bun inspect