Skip to main content
Glama
goncalompontes

Mind Forge

by goncalompontes
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Mind Forge

Ingest, query, and generate study materials from documents — all through your OpenCode chat.

Mind Forge is an OpenCode plugin that turns documents (PDFs, DOCX files, Markdown, images, web pages) into a searchable knowledge base with vector search, a knowledge graph, and study tools. You describe what you want in chat, and the LLM calls the right MCP tool automatically.

Status: MVP implemented. The full pipe — ingest → embed → graph → study — is functional.

Quick Start

# 1. Clone and install
git clone https://github.com/goncalompontes/mind-forge.git
cd mind-forge
npm install
npm run build

# 2. Register in your OpenCode config

Add to your opencode.json:

{
  "mcpServers": {
    "mind-forge": {
      "command": "node",
      "args": ["/path/to/mind-forge/dist/index.js"]
    }
  }
}

Then use it in chat:

You: Ingest the PDF at ~/papers/transformer-attention.pdf

Mind Forge: Ingested "Attention Is All You Need" (PDF, 15 chunks, 42 entities, 18 relationships)

You: Query: "how does multi-head attention work?"

Mind Forge: [3 results, scores 84–92%] Found in "Attention Is All You Need" chunk 4: "Multi-head attention allows the model to jointly attend to information from different representation subspaces..."

Related MCP server: Personal Research Assistant MCP

Architecture

Mind Forge registers three MCP tools that the LLM calls automatically:

Tool

Purpose

Pipeline

ingest

Import a document

extract → embed → store → graph

query

Search your knowledge base

vector search + graph enrichment + FTS5

generate

Create study materials

cards, quiz, exam, or review

Data Flow

Document → extract() → chunks → embed() → store (SQLite + sqlite-vec)
                                   ↘ extractEntitiesAndRelationships() → graph store
                                                   ↓
User query → embed() → vector search (ANN) → merge with FTS5 + graph enrichment → results
                                                   ↓
User request → createCards() / generateQuiz() / createExam() → study materials

Storage

  • SQLite via better-sqlite3 with WAL mode

  • Vector index via sqlite-vec (768-dimension FLOAT embeddings)

  • Full-text search via FTS5 virtual table

  • Knowledge graph in SQLite (entities + relationships tables)

  • Single file at ~/.mind-forge/store.db (configurable via MIND_FORGE_DB_PATH)

Source Format Support

Format

Extractor

Library

Notes

PDF

src/extract/pdf.ts

pdftotext CLI + pdf-parse fallback

Metadata via pdfinfo

DOCX

src/extract/docx.ts

mammoth

Metadata from docProps/core.xml

Markdown

src/extract/markdown.ts

gray-matter

Frontmatter parsing (title, author, custom fields)

Image

src/extract/image.ts

tesseract.js

PNG, JPG, JPEG, WebP; configurable OCR language

URL

src/extract/url.ts

@mozilla/readability

SSRF protection, size-limited streaming

Configuration

Mind Forge auto-detects the best embedding provider. You can configure via environment variables:

Env Variable

Purpose

Default

MIND_FORGE_DB_PATH

Database file path

~/.mind-forge/store.db

OLLAMA_HOST

Ollama server URL

http://127.0.0.1:11434

Embedding provider selection (via EmbeddingConfig):

  • auto (default) — tries Ollama first, falls back to API provider if configured

  • ollama — local Ollama (nomic-embed-text default, falls back to all-minilm, mxbai-embed-large)

  • llm — OpenAI-compatible API (requires apiKey)

Default chunk size: 1000 tokens (~4000 characters), paragraph-aware splitting.

Project Structure

src/
├── index.ts              # Plugin entry point — registers MCP server
├── types.ts              # All shared domain types (12 interfaces, 5 type aliases)
├── embed/                # Embedding providers
│   ├── provider.ts       # Factory — auto/Ollama/LLM selection
│   ├── ollama.ts         # Ollama adapter (ollama npm package)
│   └── llm-provider.ts   # OpenAI-compatible API adapter
├── extract/              # Document extraction
│   ├── index.ts          # Orchestrator + paragraph-aware chunking
│   ├── pdf.ts            # PDF via pdftotext + pdf-parse
│   ├── docx.ts           # DOCX via mammoth
│   ├── markdown.ts       # Markdown via gray-matter
│   ├── image.ts          # Image OCR via tesseract.js
│   └── url.ts            # Web pages via @mozilla/readability
├── store/                # SQLite persistence
│   ├── database.ts       # Singleton, schema, sqlite-vec init
│   ├── documents.ts      # Document + chunk CRUD
│   └── vectors.ts        # Vector insert + ANN search
├── graph/                # Knowledge graph
│   ├── extractor.ts      # Pattern-based entity/relationship extraction
│   ├── index.ts          # Graph storage (atomic transactions)
│   └── query.ts          # BFS traversal, neighbors, pathfinding
├── study/                # Study tools
│   ├── cards.ts          # SM-2 spaced repetition cards
│   ├── quiz.ts           # Quiz generation + grading (MCQ, T/F, fill-blank)
│   └── exam.ts           # Timed exam mode
└── mcp/                  # MCP server
    ├── server.ts         # Server registration + 3 tool handlers
    ├── ingest.tool.ts    # IngestTool class (extract → embed → store → graph)
    └── query.tool.ts     # QueryTool class (hybrid search)

Dependencies

Package

Purpose

@modelcontextprotocol/sdk

MCP server framework

@opencode-ai/plugin

OpenCode plugin registration

better-sqlite3

SQLite database

sqlite-vec

Vector search extension

ollama

Local embedding via Ollama

tesseract.js

Image OCR

@mozilla/readability

Web page content extraction

mammoth

DOCX text extraction

gray-matter

Markdown frontmatter parsing

pdf-parse

PDF text extraction (fallback)

jsdom

DOM parsing for Readability

Scripts

Script

Command

build

tsc

test

vitest run

typecheck

tsc --noEmit

Key Design Decisions

  • Conversational interface: All interaction through OpenCode chat via MCP tools. No slash commands, no custom UI.

  • Graceful degradation: Embedding or graph failures don't block ingestion. Document + chunks are always stored.

  • Hybrid search: Vector similarity (0.7 weight) + FTS5 BM25 (0.3 weight) merged with dedup by chunk ID.

  • Pattern-based extraction: Regex patterns for entities and relationships at MVP (LLM callback extension point available).

  • SSRF protection: URL extraction resolves hostnames to IPs and rejects private/reserved ranges before connecting.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Personal Research Assistant

    chakri01
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables semantic search and conversational querying across a personal research library of PDFs, DOCX, and other documents using a vector database. It provides tools for document summarization, finding related papers, and high-accuracy retrieval for AI clients like Claude Desktop.
    -