Factsets

Package
CI/CD	Release Tests codecov

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

Concept	Description
Facts	Atomic knowledge units (1-3 sentences), tagged and timestamped
Resources	External content (files, URLs, APIs) with cached snapshots and retrieval methods
Skills	Markdown documents for procedural knowledge, stored on filesystem
Execution Logs	Command history with success/failure tracking for skill validation
Tags	Flexible categorization for all content types

MCP Tools

Facts

Tool	Description
submit_facts	Add facts with tags and source tracking
search_facts	Query facts by tags, content, or filters
verify_facts	Mark facts as verified by ID
verify_facts_by_tags	Bulk verify facts by tags
update_fact	Update fact content, metadata, or tags
delete_facts	Remove facts by criteria
restore_facts	Restore soft-deleted facts

Resources

Tool	Description
add_resources	Register resources with retrieval methods
search_resources	Find resources by tags, type, or URI
get_resources	Get resources by ID or URI with freshness
update_resource_snapshot	Update cached content for single resource
update_resource_snapshots	Bulk update cached content
update_resource	Update resource metadata (not content)
delete_resources	Remove resources
restore_resources	Restore soft-deleted resources

Skills

Tool	Description
create_skill	Create markdown skill document
update_skill	Update skill metadata/references
search_skills	Find skills by tags or query
get_skills	Get skills by name with content
link_skill	Link skill to facts/resources/skills
sync_skill	Sync skill after file edit
delete_skills	Remove skills
get_dependency_graph	Get skill dependency tree
restore_skills	Restore soft-deleted skills

Execution Logs

Tool	Description
submit_execution_logs	Record command/test/build executions
search_execution_logs	Find executions by query, tags, success
get_execution_log	Get execution details by ID

Tags

Tool	Description
create_tags	Create organizational tags
list_tags	List tags with usage counts
update_tags	Update tag descriptions
prune_orphan_tags	Clean up unused orphan tags

Configuration

Tool	Description
get_config	Get a configuration value by key
set_config	Set a configuration value
delete_config	Delete a configuration value
list_config	List all configuration with schema
get_config_schema	Get available options with descriptions

User Preferences

Tool	Description
get_preference_prompt	Get natural language preference prompt
get_user_preferences	Get structured preference data
infer_preference	Update preference from user behavior
reset_preferences	Reset preferences to defaults

Maintenance

Tool	Description
check_stale	Find stale resources and dependencies
mark_resources_refreshed	Mark resources as current

Context & Guides

Tool	Description
get_knowledge_context	Build context from tags (facts/resources/skills)
build_skill_context	Get skill with formatted content and refs
get_maintenance_report	Generate staleness/maintenance report
get_refresh_guide	Get instructions for refreshing a resource
get_agent_guide	Get the agent workflow guide (call first)
get_concept_guide	Get conceptual overview and design philosophy
get_config_guide	Get configuration guide with all options

MCP Prompts

Prompt	Description
setup	Guided setup for new project integration
user_preferences	Get user preferences for output formatting
knowledge_context	Build context from tags
recall_skill	Get skill with references
maintenance_report	Staleness summary
refresh_guide	Instructions to refresh a resource
agent_guide	Agent workflow guide (call first)
concept	Conceptual overview and philosophy
config	Configuration guide with all options

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