stellavault 0.8.2 → 0.8.4

package/README.md

@@ -1,6 +1,6 @@
 # Stellavault
 
-[![CI](https://github.com/Evanciel/stellavault/actions/workflows/ci.yml/badge.svg)](https://github.com/Evanciel/stellavault/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/stellavault)](https://www.npmjs.com/package/stellavault) [![tests](https://img.shields.io/badge/tests-223%20passing-brightgreen)]()
+[![CI](https://github.com/Evanciel/stellavault/actions/workflows/ci.yml/badge.svg)](https://github.com/Evanciel/stellavault/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/stellavault)](https://www.npmjs.com/package/stellavault) [![tests](https://img.shields.io/badge/tests-245%20passing-brightgreen)]() [![node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)]() [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 > **Drop anything. It compiles itself into knowledge.** Claude remembers everything you know.
 
@@ -11,6 +11,10 @@ Self-compiling knowledge base with a full-featured editor, 3D neural graph, AI-p
   <br><em>Your vault as a neural network. Local-first, no cloud required.</em>
 </p>
 
+## Contents
+
+[Install](#install) · [Editor](#editor) · [Pipeline](#the-pipeline) · [Intelligence](#intelligence-what-makes-stellavault-unique) · [Search & Ranking](#search--ranking) · [MCP Integration](#mcp-integration-21-tools) · [3D Visualization](#3d-visualization) · [Configuration](#configuration) · [Performance](#performance) · [Tech Stack](#tech-stack) · [Security](#security) · [Troubleshooting](#troubleshooting)
+
 ## Install
 
 ### Desktop App (Recommended — one click)
@@ -120,6 +124,24 @@ These features do **not exist** in Obsidian — even with plugins.
 
 ---
 
+## Search & Ranking
+
+Hybrid retrieval that fuses multiple signals with **weighted Reciprocal Rank Fusion (RRF)** — tuned for a personal knowledge vault, fully local, zero API keys:
+
+| Signal | What it captures | Default weight |
+|--------|------------------|---------------:|
+| **Semantic** (dense) | meaning; multilingual (50+ languages) | `1.0` |
+| **BM25** (keyword) | exact terms, code, names | `1.0` |
+| **Entity-linking** | your `[[wikilinks]]`, `#tags`, headings, titles — the curated graph | `1.5` |
+| **FSRS recency** | gently surfaces notes you're actively using / forgetting | `±10%` |
+
+- **Entity matching** resolves natural-language queries via fuzzy substring + punctuation-normalized matching (Korean / CJK friendly), with a **per-document diversity cap** so one large note can't flood the top results.
+- **Recency** reuses the same FSRS memory model as the decay engine (not raw file mtime) — a note you're forgetting resurfaces; a mastered evergreen note isn't buried just for being old.
+- **Adaptive rerank** (long-running MCP server) further boosts results by your current session context (recent tags / paths).
+- Every weight is **tunable** per vault or via env vars — see [Configuration](#configuration).
+
+---
+
 ## MCP Integration (21 Tools)
 
 ```bash
@@ -128,13 +150,13 @@ stellavault setup            # one command → Claude Code, Claude Desktop, Curs
 claude mcp add stellavault -- stellavault serve
 ```
 
-Claude can search, ask, draft, lint, and analyze your vault directly. Search
-fuses **semantic + BM25 + entity-linking** — your `[[wikilinks]]`, tags, and
-headings become retrieval signals — with session-adaptive reranking.
+Claude can search, ask, draft, lint, and analyze your vault directly. Search runs
+the full hybrid pipeline — **weighted RRF** over semantic + BM25 + entity-linking,
+plus **FSRS recency** and session-adaptive reranking (see [Search & Ranking](#search--ranking)).
 
 | Tool | What it does |
 |------|-------------|
-| `search` | Hybrid semantic + BM25 + entity-linking, adaptive rerank |
+| `search` | Weighted RRF (semantic + BM25 + entity) + FSRS recency + adaptive rerank |
 | `ask` | Vault-grounded Q&A |
 | `generate-draft` | AI drafts from your knowledge |
 | `get-decay-status` | Memory decay report (FSRS) |
@@ -218,6 +240,34 @@ stellavault decay                         # What are you forgetting?
 
 ---
 
+## Configuration
+
+Stellavault reads `./.stellavault.json` (or `~/.stellavault.json`). Search ranking is fully tunable — sensible defaults work out of the box:
+
+```jsonc
+{
+  "search": {
+    "rrfK": 60,
+    "weights": { "semantic": 1.0, "bm25": 1.0, "entity": 1.5 },
+    "recencyWeight": 0.2,                          // FSRS recency strength; 0 = off
+    "entityAliases": { "k8s": ["kubernetes"] }     // synonym / cross-lingual groups (exact-only)
+  }
+}
+```
+
+Environment variables override config (parsed with guards):
+
+| Env var | Effect |
+|---------|--------|
+| `STELLAVAULT_W_SEMANTIC` / `_BM25` / `_ENTITY` | per-signal RRF weight (e.g. `STELLAVAULT_W_ENTITY=2.0` for aggressive entity surfacing) |
+| `STELLAVAULT_RECENCY_WEIGHT` | recency strength `0`–`1` (`0` disables) |
+| `STELLAVAULT_DB_PATH` | override the index DB location |
+| `STELLAVAULT_WATCH` | `0` to disable the auto-reindex file watcher while `serve` runs |
+
+> Note: cross-lingual recall (e.g. a Korean query finding English notes) is handled automatically by the multilingual embedding model — `entityAliases` is an optional precision boost for the curated entity graph (tags / wikilinks) and abbreviations.
+
+---
+
 ## Performance
 
 Tested on synthetic vaults — all operations under 1 second for typical use cases:
@@ -253,7 +303,7 @@ Key optimizations:
 | Runtime | Node.js 20+ (ESM, TypeScript) |
 | Vector Store | SQLite-vec (local, zero config) |
 | Embedding | MiniLM-L12-v2 (local, 50+ languages, batch processing) |
-| Search | BM25 + Cosine + RRF Fusion |
+| Search | Weighted RRF (semantic + BM25 + entity) + FSRS recency |
 | Math | KaTeX (inline + display) |
 | Code | lowlight / highlight.js (40+ languages) |
 | 3D | React Three Fiber + Three.js |

package/dist/stellavault.js

@@ -40,7 +40,9 @@ function mergeConfig(defaults, overrides) {
       ...defaults.search,
       ...overrides.search,
       // B3 §4 — deep-merge weights so a partial override keeps the other defaults.
-      weights: { ...defaults.search.weights, ...overrides.search?.weights }
+      weights: { ...defaults.search.weights, ...overrides.search?.weights },
+      // B2.2 — merge alias groups (override wins per-key).
+      entityAliases: { ...defaults.search.entityAliases, ...overrides.search?.entityAliases }
     },
     mcp: { ...defaults.mcp, ...overrides.mcp }
   };
@@ -96,8 +98,10 @@ var init_config = __esm({
         rrfK: 60,
         weights: { semantic: 1, bm25: 1, entity: 1.5 },
         // B2.1: entity leads (per-doc cap prevents flooding)
-        recencyWeight: 0.2
+        recencyWeight: 0.2,
         // B3 §1.3 (±10% bound)
+        entityAliases: {}
+        // B2.2 — user-defined synonym groups
       },
       mcp: {
         mode: "stdio",
@@ -496,6 +500,34 @@ function extractQueryTerms(query) {
   }
   return [...set].slice(0, MAX_QUERY_TERMS);
 }
+function buildAliasIndex(aliases) {
+  const index = /* @__PURE__ */ new Map();
+  if (!aliases)
+    return index;
+  for (const [key, arr] of Object.entries(aliases)) {
+    const group = [normalize(key), ...(Array.isArray(arr) ? arr : []).map(normalize)].filter(Boolean);
+    const uniq = [...new Set(group)];
+    if (uniq.length < 2)
+      continue;
+    for (const term of uniq) {
+      const others = uniq.filter((t2) => t2 !== term);
+      index.set(term, [.../* @__PURE__ */ new Set([...index.get(term) ?? [], ...others])]);
+    }
+  }
+  return index;
+}
+function expandWithAliases(terms, aliasIndex) {
+  if (!aliasIndex || aliasIndex.size === 0)
+    return terms;
+  const out = new Set(terms);
+  for (const t2 of terms) {
+    const syn = aliasIndex.get(t2);
+    if (syn)
+      for (const s of syn)
+        out.add(s);
+  }
+  return [...out].slice(0, MAX_QUERY_TERMS);
+}
 var MAX_ENTITIES_PER_CHUNK, MAX_QUERY_TERMS, STOPWORDS;
 var init_entity_extractor = __esm({
   "packages/core/dist/indexer/entity-extractor.js"() {
@@ -3905,16 +3937,17 @@ function createSqliteVecStore(dbPath, dimensions = 384) {
         // FTS5 rank is negative (lower = better)
       }));
     },
-    async searchEntities(entities, limit) {
-      if (!entities || entities.length === 0)
+    async searchEntities(entities, limit, exactExtra = []) {
+      if ((!entities || entities.length === 0) && exactExtra.length === 0)
         return [];
-      const exactPH = entities.map(() => "?").join(",");
+      const allExact = [...entities, ...exactExtra];
+      const exactPH = allExact.map(() => "?").join(",");
       const fuzzy = entities.filter((t2) => t2.length >= 4 && (/\s/.test(t2) || /[^\x00-\x7f]/.test(t2) || t2.length >= 6)).slice(0, 16);
       let matched;
       let matchedParams;
       if (fuzzy.length === 0) {
         matched = `SELECT chunk_id, CAST(COUNT(*) AS REAL) AS score FROM chunk_entities WHERE entity IN (${exactPH}) GROUP BY chunk_id`;
-        matchedParams = [...entities];
+        matchedParams = [...allExact];
       } else {
         const esc = (t2) => t2.replace(/[\\%_]/g, "\\$&");
         const likeClause = fuzzy.map(() => `entity LIKE ? ESCAPE '\\'`).join(" OR ");
@@ -3925,7 +3958,7 @@ function createSqliteVecStore(dbPath, dimensions = 384) {
             SELECT chunk_id, 0.4 AS w FROM chunk_entities
               WHERE (${likeClause}) AND entity NOT IN (${exactPH})
           ) GROUP BY chunk_id`;
-        matchedParams = [...entities, ...fuzzy.map((t2) => `%${esc(t2)}%`), ...entities];
+        matchedParams = [...allExact, ...fuzzy.map((t2) => `%${esc(t2)}%`), ...allExact];
       }
       const rows = db.prepare(`
         SELECT chunk_id, score FROM (
@@ -4143,13 +4176,14 @@ async function searchSemantic(store, embedder, query, limit) {
 
 // packages/core/dist/search/entity.js
 init_entity_extractor();
-async function searchEntities(store, query, limit) {
+async function searchEntities(store, query, limit, aliasIndex) {
   if (typeof store.searchEntities !== "function")
     return [];
   const terms = extractQueryTerms(query);
   if (terms.length === 0)
     return [];
-  return store.searchEntities(terms, limit);
+  const aliasExact = expandWithAliases(terms, aliasIndex).filter((t2) => !terms.includes(t2));
+  return store.searchEntities(terms, limit, aliasExact);
 }
 
 // packages/core/dist/search/rrf.js
@@ -4173,6 +4207,9 @@ function rrfFusionN(lists, k = 60, limit = 10, opts = {}) {
   return [...scores.entries()].sort((a, b) => b[1] - a[1]).slice(0, limit).map(([chunkId, score]) => ({ chunkId, score }));
 }
 
+// packages/core/dist/search/index.js
+init_entity_extractor();
+
 // packages/core/dist/search/adaptive.js
 function createAdaptiveSearch(deps) {
   const { baseSearch } = deps;
@@ -4243,6 +4280,7 @@ var DEFAULT_SIGNAL_WEIGHTS = {
 function createSearchEngine(deps) {
   const { store, embedder, rrfK = 60, getDecayEngine } = deps;
   const baseWeights = { ...DEFAULT_SIGNAL_WEIGHTS, ...deps.weights };
+  const aliasIndex = buildAliasIndex(deps.entityAliases);
   const FETCH_LIMIT = 30;
   return {
     async search(options) {
@@ -4251,7 +4289,7 @@ function createSearchEngine(deps) {
       const [bm25Results, semanticResults, entityResults] = await Promise.all([
         searchBm25(store, query, FETCH_LIMIT),
         searchSemantic(store, embedder, query, FETCH_LIMIT),
-        searchEntities(store, query, FETCH_LIMIT)
+        searchEntities(store, query, FETCH_LIMIT, aliasIndex)
       ]);
       const lists = [semanticResults, bm25Results, entityResults];
       const weights = [w.semantic, w.bm25, w.entity];
@@ -5757,7 +5795,7 @@ function createMcpServer(options) {
   const askTool = createAskTool(searchEngine, vaultPath);
   const generateDraftTool = createGenerateDraftTool(searchEngine, vaultPath);
   const agenticTools = embedder ? createAgenticGraphTools(store, embedder, vaultPath) : [];
-  const server = new Server({ name: "stellavault", version: "0.8.2" }, { capabilities: { tools: {} } });
+  const server = new Server({ name: "stellavault", version: "0.8.4" }, { capabilities: { tools: {} } });
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
       searchToolDef,
@@ -7963,7 +8001,9 @@ function createKnowledgeHub(config, options = {}) {
     embedder,
     rrfK: config.search.rrfK,
     weights: { semantic: sw.semantic, bm25: sw.bm25, entity: sw.entity, recency: sw.recency },
-    getDecayEngine
+    getDecayEngine,
+    entityAliases: config.search.entityAliases
+    // B2.2 — cross-lingual/synonym groups
   });
   const mcpServer = createMcpServer({ store, searchEngine, vaultPath: config.vaultPath, ready: options.ready });
   return { store, embedder, searchEngine, mcpServer, config };
@@ -8100,7 +8140,9 @@ async function searchCommand(query, options, cmd) {
     store,
     embedder,
     rrfK: config.search.rrfK,
-    weights: { semantic: sw.semantic, bm25: sw.bm25, entity: sw.entity, recency: sw.recency }
+    weights: { semantic: sw.semantic, bm25: sw.bm25, entity: sw.entity, recency: sw.recency },
+    entityAliases: config.search.entityAliases
+    // B2.2
   });
   const results = await engine.search({ query, limit });
   await store.close();
@@ -10934,7 +10976,7 @@ if (nodeVersion < 20) {
   process.exit(1);
 }
 var program = new Command();
-var SV_VERSION = true ? "0.8.2" : "0.0.0-dev";
+var SV_VERSION = true ? "0.8.4" : "0.0.0-dev";
 program.name("stellavault").description("Stellavault \u2014 Self-compiling knowledge base for your Obsidian vault").version(SV_VERSION).option("--json", "Output in JSON format (for scripting)").option("--quiet", "Suppress non-essential output");
 program.command("init").description("Interactive setup wizard \u2014 get started in 3 minutes").action(initCommand);
 program.command("doctor").description("Diagnose setup issues (config, vault, DB, model, Node version)").action(doctorCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stellavault",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Drop anything. It compiles itself into knowledge. Claude remembers everything you know. Local-first MCP server, vault files never modified.",
   "repository": {
     "type": "git",