mindlore 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mindlore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# Mindlore
+
+AI-native knowledge system for [Claude Code](https://claude.ai/claude-code).
+
+Persistent, searchable, evolving knowledge base that compounds across sessions.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-20%2B-green.svg)](https://nodejs.org)
+
+## Why
+
+Claude Code forgets everything between sessions. Your corrections, discoveries, and decisions vanish. Mindlore gives Claude a persistent memory:
+
+- **Knowledge persists** across sessions via FTS5-indexed Markdown files
+- **Search happens automatically** — hooks inject relevant context as you work
+- **Knowledge compounds** — query answers become searchable for future sessions
+
+## Why Mindlore?
+
+| Feature | Mindlore | Typical KB CLI | Wiki Compilers | Multi-Agent Memory |
+|---------|----------|---------------|----------------|-------------------|
+| Zero workflow change | Hook-based, invisible | Manual commands | Manual compile | Agent orchestration |
+| Persistent search | FTS5 auto-indexed | Manual index | No search | Vector DB overhead |
+| Knowledge compounding | Writeback loop | No | No | Partial |
+| Token efficient | Progressive disclosure | Full dump | Full dump | Varies |
+| Setup time | `npx mindlore init` | Config + setup | Complex | Complex |
+
+## Quick Start
+
+```bash
+npx mindlore init
+```
+
+That's it. Mindlore creates a `.mindlore/` directory, sets up hooks, and starts working.
+
+To add your first source:
+
+```
+/mindlore-ingest https://example.com/article
+```
+
+## Features
+
+| Skill | Version | Description |
+|-------|---------|-------------|
+| `/mindlore-ingest` | v0.1 | Add knowledge sources (URL, text, file, PDF) |
+| `/mindlore-health` | v0.1 | 16-point structural health check |
+| `/mindlore-query` | v0.2 | Search and retrieve knowledge (4 modes) |
+| `/mindlore-log` | v0.2 | Session logging with reflect and status |
+| `/mindlore-decide` | v0.2 | Decision records with supersedes chain |
+| `/mindlore-evolve` | v0.3 | Schema co-evolution and structural updates |
+| `/mindlore-explore` | v0.3 | Cross-reference discovery between sources |
+
+## Architecture
+
+Knowledge flows through a compiler-like pipeline:
+
+```
+raw/        Immutable source captures (URL dumps, pasted text)
+  |
+sources/    Processed summaries (one per ingested source)
+  |
+domains/    Topic wiki pages (accumulated knowledge by subject)
+  |
+insights/   Query writebacks (answers that become searchable)
+```
+
+Nine directories, each mapping to a frontmatter `type`:
+
+```
+.mindlore/
+├── raw/            # Immutable captures
+├── sources/        # Processed summaries
+├── domains/        # Topic wikis
+├── analyses/       # Large syntheses (3+ sources)
+├── insights/       # Short Q&A writebacks
+├── connections/    # Cross-cutting links
+├── learnings/      # Persistent rules from reflect
+├── diary/          # Session deltas
+├── decisions/      # Decision records
+├── INDEX.md        # Navigation map (~15 lines)
+├── SCHEMA.md       # LLM specification
+└── mindlore.db     # FTS5 search database
+```
+
+## Installation
+
+### Minimal (default)
+
+```bash
+npx mindlore init
+```
+
+Requires: Node.js 20+, `better-sqlite3` (installed automatically).
+
+### Recommended
+
+```bash
+npx mindlore init --recommended
+```
+
+Also suggests installing:
+- **markitdown** — better web/document extraction (URL, DOCX, YouTube)
+- **context-mode** — token savings for large sessions
+
+## Hooks
+
+Mindlore works through 7 Claude Code lifecycle hooks (v0.1):
+
+| Event | Hook | What it does |
+|-------|------|-------------|
+| SessionStart | session-focus | Injects last delta + INDEX |
+| UserPromptSubmit | search | FTS5 search, top 3 results |
+| FileChanged | index | Sync changed files to FTS5 |
+| FileChanged | fts5-sync | Incremental batch re-index |
+| SessionEnd | session-end | Write delta to diary/ |
+| PreCompact | pre-compact | FTS5 flush before compaction |
+| PostCompact | post-compact | Re-inject context |
+
+## Inspired By
+
+- [Andrej Karpathy](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — LLM Knowledge Bases concept
+- [Spisak](https://github.com/nickspisak) — Practical second brain implementations
+- [Letta](https://github.com/letta-ai/letta-code) — Context repository pattern validation
+
+## License
+
+[MIT](LICENSE)

package/SCHEMA.md

@@ -0,0 +1,221 @@
+# Mindlore Schema
+
+This file is the single source of truth for how the `.mindlore/` knowledge base works.
+It is written for LLM agents — not humans. Every rule here must be followed exactly.
+
+## 1. Identity
+
+Mindlore is an AI-native knowledge system. It stores, indexes, and evolves knowledge
+across Claude Code sessions. Knowledge lives in `.mindlore/` as plain Markdown files
+with YAML frontmatter. Search is powered by FTS5 (SQLite full-text search).
+
+## 2. Directory Structure
+
+```
+.mindlore/
+├── raw/            # Immutable source captures (URL dumps, pasted text)
+├── sources/        # Processed source summaries (one per ingested source)
+├── domains/        # Topic wiki pages (entities + concepts)
+├── analyses/       # Large syntheses (200+ lines, 3+ sources)
+├── insights/       # Short Q&A writebacks (<200 lines, 1-2 sources)
+├── connections/    # Cross-cutting links between 2+ sources
+├── learnings/      # Persistent rules extracted from reflect (topic-based)
+├── diary/          # Session logs, delta files (delta-YYYY-MM-DD-HHmm.md)
+├── decisions/      # Decision records with context and rationale
+├── INDEX.md        # Minimal navigation map (~15-20 lines, fixed size)
+├── SCHEMA.md       # This file (copied from repo template)
+├── log.md          # Operation log (append-only)
+└── mindlore.db     # FTS5 search database (SQLite)
+```
+
+### Directory Rules
+
+- Each directory corresponds to exactly one frontmatter `type` value
+- `type: raw` → `raw/`, `type: source` → `sources/`, etc.
+- Files MUST live in the directory matching their `type`
+- The health check script validates this cross-reference
+
+## 3. Frontmatter
+
+Every `.md` file in `.mindlore/` MUST have YAML frontmatter. Format:
+
+```yaml
+---
+slug: kebab-case-unique-identifier
+type: raw|source|domain|analysis|insight|connection|learning|decision|diary
+title: Human-readable title
+tags: [tag1, tag2]
+---
+```
+
+### Required Fields (all types)
+
+| Field | Format | Rule |
+|-------|--------|------|
+| `slug` | kebab-case | Unique within directory. Used as filename: `{slug}.md` |
+| `type` | enum | Must match the parent directory (see Section 2) |
+
+### Type-Specific Fields
+
+| Type | Required Fields | Optional |
+|------|----------------|----------|
+| `raw` | slug, type, source_url | tags |
+| `source` | slug, type, title, tags, quality, source_url, ingested | date_captured |
+| `domain` | slug, type, title, tags | — |
+| `analysis` | slug, type, title, tags, confidence, sources_used | — |
+| `insight` | slug, type, title, tags | sources_used |
+| `connection` | slug, type, title, tags | sources_used |
+| `learning` | slug, type, title, tags | — |
+| `decision` | slug, type, title, tags | supersedes, status |
+| `diary` | slug, type, date | — (hook adds automatically) |
+
+### Field Value Rules
+
+- `quality`: `high` | `medium` | `low`
+- `confidence`: `high` | `medium` | `low` (how certain is this analysis)
+- `ingested`: `true` | `false` (has this source been processed into domains)
+- `sources_used`: list of slugs referenced in the analysis
+- `supersedes`: slug of the decision this one replaces
+- `date`: ISO 8601 date (YYYY-MM-DD)
+
+## 4. Seven Operations
+
+### 4.1 Ingest (skill: /mindlore-ingest)
+
+Add new knowledge. Flow: capture → raw/ → process → sources/ → update domains/ → FTS5.
+
+- URL mode: markitdown CLI (if available) or WebFetch → raw/ → Sonnet summarizes → sources/
+- Text mode: user paste → raw/ → summarize → sources/
+- PDF mode: CC Read tool (max 20 pages/request) → raw/ → summarize → sources/
+- **markitdown is NOT used for PDF** — quality is poor. Use CC Read tool or Marker/Chandra (v0.3+)
+
+### 4.2 Query (skill: /mindlore-query, v0.2 — PLANNED, not yet implemented)
+
+Search and retrieve knowledge. Four modes:
+- `search`: FTS5 keyword search, return top 3 matches with snippets
+- `ask`: Natural language question → FTS5 → read relevant files → synthesize answer
+- `stats`: Knowledge base statistics (counts by type, recent activity)
+- `brief`: Quick context on a topic (read domain page if exists)
+
+### 4.3 Health (skill: /mindlore-health)
+
+Run 16-point structural check:
+- 9 directory existence checks
+- SCHEMA.md parse validation
+- INDEX.md format check (~15-20 lines)
+- mindlore.db FTS5 integrity
+- Orphan file detection (files not in FTS5)
+- Frontmatter validation (type-directory cross-reference)
+
+### 4.4 Log (skill: /mindlore-log, v0.2 — PLANNED, not yet implemented)
+
+Session logging with four modes:
+- `log`: Write session/task record to diary/
+- `reflect`: Scan old deltas, extract patterns, move to learnings/
+- `status`: Recent N sessions summary, trends, open items
+- `save`: Structured delta + log.md append + wiki update
+
+### 4.5 Decide (skill: /mindlore-decide, v0.2 — PLANNED, not yet implemented)
+
+Record decisions with context, options considered, rationale, and outcome.
+Supports `supersedes` chain for decision evolution.
+
+### 4.6 Evolve (skill: /mindlore-evolve, v0.3 — PLANNED, not yet implemented)
+
+Schema co-evolution. Scan domains + sources, suggest structural updates.
+Run monthly or after major changes.
+
+### 4.7 Explore (skill: /mindlore-explore, v0.3 — PLANNED, not yet implemented)
+
+Discover unexpected connections between sources. Cross-reference analysis.
+
+## 5. Search Behavior
+
+### FTS5 Search (hooks + scripts)
+
+- Database: `.mindlore/mindlore.db`
+- Table: `mindlore_fts` (columns: path, content)
+- Dedup: `file_hashes` table with SHA256 content-hash
+- Tokenizer: `unicode61`
+- Max results: 3 per query (BM25 ranking)
+- Hook injects: file path + first 2 headings
+
+### Search Flow (UserPromptSubmit hook)
+
+1. Extract keywords from user prompt
+2. Query FTS5 with BM25 ranking
+3. Return max 3 results as stderr additionalContext
+4. Agent reads full file only if needed (progressive disclosure)
+
+## 6. Compounding
+
+Knowledge compounds when outputs become inputs:
+
+```
+Query answer → writeback to insights/ → FTS5 indexes → next query finds it
+Reflect → patterns to learnings/ → session-focus injects → agent applies
+```
+
+### Writeback Triggers
+
+Offer to save when:
+- Comparison table generated (X vs Y)
+- Architectural decision or evaluation made
+- 3+ sources synthesized
+- User says "save this" or "remember this"
+
+### Writeback Rules
+
+- Short answer (<200 lines) → insights/
+- Large synthesis (200+ lines, 3+ sources) → analyses/
+- Cross-cutting link → connections/
+
+## 7. Learnings
+
+Persistent rules extracted from reflect operations.
+Organized by topic: `git.md`, `testing.md`, `security.md`, etc.
+
+### Format
+
+```markdown
+---
+slug: testing
+type: learning
+title: Testing Learnings
+tags: [testing, jest, mock]
+---
+
+# Testing Learnings
+
+- YAPMA: Error handling testinde mock'u dolayli tetikleme
+- BEST PRACTICE: Side-effect'li moduller eklerken TUM test'lerde mock ekle
+```
+
+### Rules
+
+- One file per topic (not per lesson)
+- Append new learnings to existing topic file
+- Use `YAPMA:` / `BEST PRACTICE:` / `KRITIK:` prefixes
+- Reflect skill proposes, user approves before writing
+
+## 8. Naming Conventions
+
+### Files
+
+- Filename = `{slug}.md` (kebab-case)
+- Diary: `delta-YYYY-MM-DD-HHmm.md`
+- No spaces, no uppercase in filenames
+
+### Slugs
+
+- kebab-case only: `my-analysis-topic`
+- Unique within directory
+- Descriptive but concise (3-5 words max)
+
+### INDEX.md
+
+- Fixed size: ~15-20 lines
+- Domain list (entities/concepts headings)
+- Stats line: "N source, N analysis, N total"
+- Last 5 added (initially empty)
+- NO full file listing — discovery via FTS5

package/hooks/lib/mindlore-common.cjs

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * Shared utilities for mindlore hooks.
+ * Eliminates duplication of findMindloreDir, getLatestDelta, sha256, etc.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const os = require('os');
+
+const MINDLORE_DIR = '.mindlore';
+const DB_NAME = 'mindlore.db';
+const SKIP_FILES = new Set(['INDEX.md', 'SCHEMA.md', 'log.md']);
+
+function findMindloreDir() {
+  const projectDir = path.join(process.cwd(), MINDLORE_DIR);
+  if (fs.existsSync(projectDir)) return projectDir;
+
+  const globalDir = path.join(os.homedir(), MINDLORE_DIR);
+  if (fs.existsSync(globalDir)) return globalDir;
+
+  return null;
+}
+
+function getLatestDelta(diaryDir) {
+  if (!fs.existsSync(diaryDir)) return null;
+
+  const deltas = fs
+    .readdirSync(diaryDir)
+    .filter((f) => f.startsWith('delta-') && f.endsWith('.md'))
+    .sort()
+    .reverse();
+
+  if (deltas.length === 0) return null;
+  return path.join(diaryDir, deltas[0]);
+}
+
+function sha256(content) {
+  return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
+}
+
+function requireDatabase() {
+  try {
+    return require('better-sqlite3');
+  } catch (_err) {
+    return null;
+  }
+}
+
+function openDatabase(dbPath, opts) {
+  const Database = requireDatabase();
+  if (!Database) return null;
+
+  const db = new Database(dbPath, opts);
+  if (!opts || !opts.readonly) {
+    db.pragma('journal_mode = WAL');
+  }
+  return db;
+}
+
+function getAllMdFiles(dir, skip) {
+  const skipSet = skip || SKIP_FILES;
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...getAllMdFiles(fullPath, skipSet));
+    } else if (entry.name.endsWith('.md') && !skipSet.has(entry.name)) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+module.exports = {
+  MINDLORE_DIR,
+  DB_NAME,
+  SKIP_FILES,
+  findMindloreDir,
+  getLatestDelta,
+  sha256,
+  requireDatabase,
+  openDatabase,
+  getAllMdFiles,
+};

package/hooks/mindlore-fts5-sync.cjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * mindlore-fts5-sync — FileChanged hook (incremental re-index)
+ *
+ * Handles bulk file changes by checking all .mindlore/ .md files
+ * against their content hashes and re-indexing only changed ones.
+ *
+ * Lightweight complement to mindlore-index.cjs which handles single files.
+ * This hook catches cases where multiple files change at once (e.g., git pull).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { MINDLORE_DIR, DB_NAME, sha256, requireDatabase, getAllMdFiles } = require('./lib/mindlore-common.cjs');
+
+function main() {
+  // Read stdin to check if this is a .mindlore/ file change
+  let input = '';
+  try {
+    input = fs.readFileSync(0, 'utf8').trim();
+  } catch (_err) {
+    // No stdin — skip
+  }
+
+  let filePath = '';
+  try {
+    const parsed = JSON.parse(input);
+    filePath = parsed.path || parsed.file_path || '';
+  } catch (_err) {
+    filePath = input;
+  }
+
+  // Only trigger on .mindlore/ changes (empty filePath = skip)
+  if (!filePath || !filePath.includes(MINDLORE_DIR)) return;
+
+  const baseDir = path.join(process.cwd(), MINDLORE_DIR);
+  if (!fs.existsSync(baseDir)) return;
+
+  const dbPath = path.join(baseDir, DB_NAME);
+  if (!fs.existsSync(dbPath)) return;
+
+  const Database = requireDatabase();
+  if (!Database) return;
+
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+
+  const mdFiles = getAllMdFiles(baseDir);
+  let synced = 0;
+
+  const getHash = db.prepare('SELECT content_hash FROM file_hashes WHERE path = ?');
+  const deleteFts = db.prepare('DELETE FROM mindlore_fts WHERE path = ?');
+  const insertFts = db.prepare('INSERT INTO mindlore_fts (path, content) VALUES (?, ?)');
+  const upsertHash = db.prepare(`
+    INSERT INTO file_hashes (path, content_hash, last_indexed)
+    VALUES (?, ?, ?)
+    ON CONFLICT(path) DO UPDATE SET
+      content_hash = excluded.content_hash,
+      last_indexed = excluded.last_indexed
+  `);
+
+  const now = new Date().toISOString();
+
+  try {
+    const transaction = db.transaction(() => {
+      for (const file of mdFiles) {
+        const content = fs.readFileSync(file, 'utf8').replace(/\r\n/g, '\n');
+        const hash = sha256(content);
+
+        const existing = getHash.get(file);
+        if (existing && existing.content_hash === hash) continue;
+
+        deleteFts.run(file);
+        insertFts.run(file, content);
+        upsertHash.run(file, hash, now);
+        synced++;
+      }
+    });
+    transaction();
+  } finally {
+    db.close();
+  }
+
+  if (synced > 0) {
+    process.stderr.write(`[Mindlore FTS5 Sync: ${synced} files re-indexed]\n`);
+  }
+}
+
+main();

package/hooks/mindlore-index.cjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * mindlore-index — FileChanged hook
+ *
+ * When a .md file in .mindlore/ changes, update its FTS5 entry.
+ * Reads changed file path from stdin (CC FileChanged event).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { MINDLORE_DIR, DB_NAME, SKIP_FILES, sha256, requireDatabase } = require('./lib/mindlore-common.cjs');
+
+function main() {
+  let input = '';
+  try {
+    input = fs.readFileSync(0, 'utf8').trim();
+  } catch (_err) {
+    return;
+  }
+
+  let filePath = '';
+  try {
+    const parsed = JSON.parse(input);
+    filePath = parsed.path || parsed.file_path || '';
+  } catch (_err) {
+    filePath = input;
+  }
+
+  if (!filePath) return;
+
+  // Only process .md files inside .mindlore/
+  if (!filePath.includes(MINDLORE_DIR) || !filePath.endsWith('.md')) return;
+
+  const fileName = path.basename(filePath);
+  if (SKIP_FILES.has(fileName)) return;
+
+  // Find the .mindlore dir from the file path
+  const mindloreIdx = filePath.indexOf(MINDLORE_DIR);
+  const baseDir = filePath.slice(0, mindloreIdx + MINDLORE_DIR.length);
+  const dbPath = path.join(baseDir, DB_NAME);
+
+  if (!fs.existsSync(dbPath)) return;
+
+  const Database = requireDatabase();
+  if (!Database) return;
+
+  if (!fs.existsSync(filePath)) {
+    // File was deleted — remove from index
+    const db = new Database(dbPath);
+    db.pragma('journal_mode = WAL');
+    try {
+      db.prepare('DELETE FROM mindlore_fts WHERE path = ?').run(filePath);
+      db.prepare('DELETE FROM file_hashes WHERE path = ?').run(filePath);
+    } finally {
+      db.close();
+    }
+    return;
+  }
+
+  const content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
+  const hash = sha256(content);
+
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+
+  try {
+    // Check if content changed
+    const existing = db
+      .prepare('SELECT content_hash FROM file_hashes WHERE path = ?')
+      .get(filePath);
+
+    if (existing && existing.content_hash === hash) return; // Unchanged
+
+    // Update FTS5
+    db.prepare('DELETE FROM mindlore_fts WHERE path = ?').run(filePath);
+    db.prepare('INSERT INTO mindlore_fts (path, content) VALUES (?, ?)').run(
+      filePath,
+      content
+    );
+
+    // Update hash
+    db.prepare(
+      `INSERT INTO file_hashes (path, content_hash, last_indexed)
+       VALUES (?, ?, ?)
+       ON CONFLICT(path) DO UPDATE SET
+         content_hash = excluded.content_hash,
+         last_indexed = excluded.last_indexed`
+    ).run(filePath, hash, new Date().toISOString());
+  } finally {
+    db.close();
+  }
+}
+
+main();

package/hooks/mindlore-post-compact.cjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * mindlore-post-compact — PostCompact hook
+ *
+ * After context compaction, re-inject session context:
+ * 1. Read INDEX.md
+ * 2. Read latest delta
+ * 3. Inject via stderr (same as session-focus)
+ *
+ * This ensures the agent has knowledge context after compaction.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { findMindloreDir, getLatestDelta } = require('./lib/mindlore-common.cjs');
+
+function main() {
+  const baseDir = findMindloreDir();
+  if (!baseDir) return;
+
+  const output = [];
+
+  // Re-inject INDEX.md
+  const indexPath = path.join(baseDir, 'INDEX.md');
+  if (fs.existsSync(indexPath)) {
+    const content = fs.readFileSync(indexPath, 'utf8').trim();
+    output.push(`[Mindlore INDEX (post-compact)]\n${content}`);
+  }
+
+  // Re-inject latest delta
+  const diaryDir = path.join(baseDir, 'diary');
+  const latestDelta = getLatestDelta(diaryDir);
+  if (latestDelta) {
+    const deltaContent = fs.readFileSync(latestDelta, 'utf8').trim();
+    const deltaName = path.basename(latestDelta);
+    output.push(`[Mindlore Delta (post-compact): ${deltaName}]\n${deltaContent}`);
+  }
+
+  if (output.length > 0) {
+    process.stderr.write(output.join('\n\n') + '\n');
+  }
+}
+
+main();