factum-mcp 1.2.4

Factum MCP Server

Your personal knowledge base with AI-powered fact management and semantic search

Factum is an MCP (Model Context Protocol) server that helps you store, organize, and query your personal knowledge. Use it to capture facts, approve staging entries, and build a growing repository of verified information with hybrid search (keyword + semantic).

🚀 Quick Start

Option 1: .NET Global Tool (Recommended)

# Install
dotnet tool install -g factum-mcp

# Run
factum-mcp

Option 2: Manual Download (No .NET Required)

1. Download the latest factum-mcp-v*.zip from Releases
2. Extract to C:\Tools\factum-mcp\
3. Run factum-mcp.exe

Option 3: Build from Source

# Clone and build
git clone https://github.com/romansource/factum-mcp
cd factum-mcp
dotnet build -c Release

# Run
dotnet run --project src/factum-mcp.csproj --no-build

🌐 Embedding Setup (Optional)

Factum works with keyword-only search by default. For semantic search, configure an OpenAI-compatible embedding API:

🏠 Local/Private (Recommended)

{
  "Embedding__BaseUrl": "http://your-server:11434/v1",
  "Embedding__ApiKey": "",
  "Embedding__Model": "all-minilm:22m"
}

💡 your-server can be localhost, 192.168.1.100, or any IP on your network.
🔒 Ensure port 11434 is open on the embedding server if accessing remotely.

☁️ Cloud/High-Quality

{
  "Embedding__BaseUrl": "https://api.openai.com/v1",
  "Embedding__ApiKey": "sk-...",
  "Embedding__Model": "text-embedding-3-small"
}

🧪 Testing/Offline

Omit Embedding__BaseUrl → Factum auto-fallbacks to keyword-only search.

⚠️ Critical: If you change Embedding__Model or BaseUrl, run rebuild_embeddings to re-embed all facts. Mixing embeddings from different models breaks semantic search.

✨ Key Features

🛠 Configure MCP Client

Add the following to your MCP client's configuration (e.g., Cline's settings.json, OpenCode's mcp.json):

{
  "mcpServers": {
    "factum": {
      "command": "factum-mcp",
      "cwd": "${workspaceFolder}"
    }
  }
}

🧩 Available Tools

Because Factum implements the tools/list MCP capability, your client will automatically discover these tools and their input schemas:

1. search_facts: Search the knowledge base using BM25 + semantic vector similarity.
2. retrieve_relevant_facts: Token-budgeted retrieval to fetch relevant facts while adhering to context limits.
3. propose_fact: Propose a new fact for review. Goes to staging and is NOT searchable until approved.
4. approve_fact: Approve a staging fact to move it to permanent, searchable storage.
5. decline_fact: Reject a staging fact. Removes it permanently so it will never be auto-approved.
6. list_staging_facts: List all facts pending approval in staging.
7. update_fact: Propose an update to an existing fact (creates a staging entry for review).
8. evaluate_fact_quality: Check for redundancy and quality before proposing a new fact.
9. get_memory_summary: Provide a compact statistical breakdown and topic summary.
10. generate_project_summary: Generate a comprehensive overview of the entire knowledge base.
11. rebuild_embeddings: Re-embed all approved facts. Required after changing model or BaseURL.

🔁 Staging Workflow: Drafts Before Publishing

Think of staging like a "drafts" folder — the AI can suggest facts, but nothing becomes part of your permanent knowledge base until you approve it.

The Full Cycle

1. AI proposes a fact → saved as a draft (not visible to the AI in conversation)
2. You review the draft — either via the MCP tool or by opening the file
3. You either:
   ✅ Approve  → the fact becomes permanent and searchable
   ❌ Decline → the fact is permanently removed

Step-by-Step Example

You speak naturally. The LLM agent calls the tool behind the scenes:

user: Can you remember that git rebase is for linear history and merge is for shared branches?

The tool returns a structured review card:

📝 New Fact Proposed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Description: Git Rebase vs Merge
Text:
      Use git rebase for linear history on topic branches.
      Use git merge for integrating shared branches.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⚠️ REVIEW REQUIRED — not searchable until approved
Staging ID: staging:a1b2c3d4

Actions:
  → approve_fact(id="staging:a1b2c3d4")
  → decline_fact(id="staging:a1b2c3d4")

You review and approve (after the 10-second delay):

user: approve_fact(id="staging:a1b2c3d4")
→ ✅ Fact approved: fact:git/rebase-vs-merge

Or decline it if it's wrong:

user: decline_fact(id="staging:a1b2c3d4")
→ ✅ Fact declined and removed

How to Review

You have two options:

Why the 10-Second Delay?

The system enforces a minimum 10-second wait between proposing and approving. This prevents the AI from auto-approving its own suggestions and gives you time to review.

What Happens to Unapproved Facts?

Staging facts accumulate in facts_staging.md until you approve or decline them. They are never visible to the AI during conversation, never returned in search results, and never included in memory summaries.

Config Options

{
  "Staging": {
    "RequireManualApproval": true,      // Enforce review before approval
    "MinApprovalDelaySeconds": 10       // Minimum seconds before approval allowed
  },
  "AutoProposal": {                     // Configuration for agent auto-proposing
    "Enabled": true,
    "RequireApproval": true,        // Set false to bypass staging (use with caution)
    "MinQualityScore": 70,           // Only propose high-quality facts
    "RepetitionWindowSeconds": 300,  // Detect repeated topics in 5-min window
    "RepetitionThreshold": 3,        // Propose after 3 similar queries
    "MaxProposalsPerSession": 20,    // Rate limiting
    "MaxProposalsPerHour": 50,       // Hourly rate limiting
    "CooldownSeconds": 30,           // Minimum seconds between proposals
    "TriggerOnLowRelevanceSearch": true,
    "TriggerOnRepeatedQuery": true,
    "TriggerOnLongResponse": false,
    "IncludePatterns": [],
    "ExcludePatterns": [],
    "ExcludeTools": []
  }
}

🤖 Auto-Proposal (Optional)

Factum can proactively suggest facts based on usage patterns. Configure via AutoProposal section:

{
  "AutoProposal": {
    "Enabled": true,
    "RequireApproval": false,        // Set false to bypass staging (use with caution)
    "MinQualityScore": 70,           // Only propose high-quality facts
    "RepetitionWindowSeconds": 300,  // Detect repeated topics in 5-min window
    "RepetitionThreshold": 3,        // Propose after 3 similar queries
    "MaxProposalsPerSession": 20,    // Rate limiting
    "TriggerOnLowRelevanceSearch": true
  }
}

🎯 Use Cases

🔁 How Repetition Detection Works

1. Factum tracks semantic hashes of queries/fact content per session
2. If similar content (≥85% similarity) appears ≥3 times in 5 minutes → auto-propose
3. Quality gate ensures only clear, non-redundant facts are proposed

⚠️ Warning: RequireApproval: false bypasses the staging workflow. Use only if you trust the auto-proposal logic or plan to review facts.md regularly.

🔍 Hybrid Search Explained

Factum uses a hybrid search algorithm combining:

1. BM25 Keyword Scoring (40%): Fast, exact phrase matching.
2. Cosine Similarity (60%): Semantic similarity using OpenAI-compatible embeddings, cached locally in SQLite.

(Falls back seamlessly to keyword-only search if the embedding server is unavailable).

📝 Facts File Format

Facts are stored in Markdown with frontmatter:

---
id: fact:async/await:patterns
description: Async/Await Patterns
created: 2026-03-30
---
Always await async calls to avoid deadlocks. Use ConfigureAwait(false) in libraries. CancellationToken for cleanup. Task.Run only for CPU-bound work; I/O is already async.

File Locations

Recommendation: Add to .gitignore for personal use:

facts.md
facts_staging.md
factum.db

⚙️ Configuration

Configure via appsettings.json or environment variables:

🧪 Testing

The project includes an integration test suite with 40 tests covering all 11 MCP tools:

# Run integration tests
dotnet run --project integration_tests/integration_tests.csproj

Tests use a temporary directory with a fresh SQLite database and BM25 index, then clean up on exit. They validate both happy paths and error handling (missing params, invalid IDs, empty results).