mindgraph-core

A local-first knowledge graph engine for Markdown notes. Extracts entities, concepts, locations, events, beliefs, emotions, reasoning chains, and contradictions, stores them in SQLite as a typed knowledge graph, and queries them with full-text and semantic search.

Install

npm install mindgraph-core

What's included

• Schema — 12 node types (Entity, Concept, Location, Event, Proposition, Thought, Emotion, EmotionalEvent, ReasoningChain, ReasoningStep, Agent, Note) and 22 typed edge types with provenance tracking
• Storage — MemoryAdapter for testing, SqliteAdapter (sql.js/WASM) with crash-safe atomic writes, FTS4, and auto-migrations
• Ingestion — Heading-aware Markdown chunker with stable content-hash IDs, plus IngestionPipeline to orchestrate chunk, extract, embed, store
• Extraction — BasicExtractor (regex/wiki-link/tag heuristics), OllamaExtractor (local LLM), OpenAIExtractor, AnthropicExtractor — LLM extractors run 5 parallel calls for entities, propositions, thoughts, emotions, and reasoning chains
• Location & event extraction — Identifies places (city, country, region) and events (with dates, participants) from note text
• Emotion tracking — Extracts emotional states (valence/arousal) and emotional events with triggers and context
• Reasoning chain extraction — Identifies structured arguments with premise → inference → conclusion steps
• Relationship extraction — Discovers IS_A, PART_OF, LOCATED_IN, OCCURRED_AT, PRECEDES, CAUSES, PARTICIPATED_IN, and other typed relationships
• Author attribution — Creates AUTHORED_BY edges from frontmatter author fields
• Entity resolution — Alias normalization and fast lookup via EntityIndex for entities, concepts, locations, and events
• Contradiction detection — Finds conflicting claims across notes with topic-grounded filtering
• Open loop detection — Surfaces unresolved questions, TODOs, and uncertainties
• Embeddings — TransformersEmbedder (in-process ONNX/WASM) and OllamaEmbedder, with batch support
• Query engine — Full-text search, semantic search, belief queries, timeline, contradiction queries, graph traversal, and citation building
• Export/import — Full data portability in JSONL format

Quick start

import { MemoryAdapter, IngestionPipeline, BasicExtractor, QueryEngine } from 'mindgraph-core';

// Set up storage and extraction
const storage = new MemoryAdapter();
await storage.initialize();

const pipeline = new IngestionPipeline({ storage, extractor: new BasicExtractor() });

// Index a note
await pipeline.ingest({
  notePath: 'notes/philosophy.md',
  content: '# Stoicism\nMarcus Aurelius believed that virtue is the sole good.',
});

// Query the graph
const engine = new QueryEngine(storage);
const results = await engine.query({ query: 'Marcus Aurelius', mode: 'search' });

Extraction tiers

| Tier | Provider | Setup | |------|----------|-------| | Basic (default) | BasicExtractor | None — regex + wiki-link + tag heuristics | | Ollama | OllamaExtractor | Local LLM via Ollama | | OpenAI | OpenAIExtractor | API key required | | Anthropic | AnthropicExtractor | API key required |

API overview

Storage

import { SqliteAdapter, MemoryAdapter } from 'mindgraph-core';

// SQLite (persistent, crash-safe)
const db = new SqliteAdapter('/path/to/graph.db');
await db.initialize();

// In-memory (for testing)
const mem = new MemoryAdapter();
await mem.initialize();

Ingestion

import { IngestionPipeline, BasicExtractor } from 'mindgraph-core';

const pipeline = new IngestionPipeline({ storage, extractor: new BasicExtractor() });
const stats = await pipeline.ingest({ notePath: 'note.md', content: '...' });
// stats: { entities: 3, concepts: 1, propositions: 2, chunks: 4, locations: 1, events: 0, ... }

Query

import { QueryEngine } from 'mindgraph-core';

const engine = new QueryEngine(storage);

// Full-text search
const results = await engine.query({ query: 'stoicism', mode: 'search' });

// Belief query
const beliefs = await engine.query({ query: 'free will', mode: 'beliefs' });

// Contradictions
const contradictions = await engine.query({ query: 'ethics', mode: 'contradictions' });

Export/Import

import { GraphExporter, GraphImporter } from 'mindgraph-core';

// Export
const exporter = new GraphExporter(storage);
const jsonl = await exporter.export();

// Import with merge
const importer = new GraphImporter(storage);
const result = await importer.import(jsonl, { strategy: 'merge' });

Requirements

• Node.js 18+
• ESM only ("type": "module")

License

MIT