mindgraph-core 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,119 @@
+# mindgraph-core
+
+A local-first knowledge graph engine for Markdown notes. Extracts entities, concepts, beliefs, and contradictions, stores them in SQLite, and queries them with full-text and semantic search.
+
+## Install
+
+```bash
+npm install mindgraph-core
+```
+
+## What's included
+
+- **Schema** — Typed graph primitives (entities, concepts, propositions, thoughts, beliefs) 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`
+- **Entity resolution** — Alias normalization and fast lookup via `EntityIndex`
+- **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
+
+```typescript
+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](https://ollama.com) |
+| **OpenAI** | `OpenAIExtractor` | API key required |
+| **Anthropic** | `AnthropicExtractor` | API key required |
+
+## API overview
+
+### Storage
+
+```typescript
+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
+
+```typescript
+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 }
+```
+
+### Query
+
+```typescript
+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
+
+```typescript
+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

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "mindgraph-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
+  "description": "Local-first knowledge graph engine for Markdown notes — extracts entities, concepts, beliefs, and contradictions",
+  "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "dependencies": {
     "sql.js": "^1.11.0",