ralph-hero-knowledge-index 0.1.21 → 0.1.24

package/src/__tests__/reindex.test.ts

@@ -4,21 +4,41 @@ import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { findMarkdownFiles } from "../file-scanner.js";
 import { FtsSearch } from "../search.js";
+import { VectorSearch } from "../vector-search.js";
+
+// Mock embedder so we don't load the real transformer model during tests.
+// embedDocument returns one DocumentChunk per call with a constant 384-dim
+// embedding; this matches the new chunk-aware reindex flow.
+vi.mock("../embedder.js", async () => {
+  // Import the real chunker so the mock chunks content the same way as prod.
+  const { chunkText } = await import("../chunker.js");
+  return {
+    embed: vi.fn(async () => new Float32Array(384)),
+    embedDocument: vi.fn(async (_title: string, _tags: string[], content: string) => {
+      const chunks = content.length === 0
+        ? [{ index: 0, content: "", charStart: 0, charEnd: 0 }]
+        : chunkText(content);
+      return chunks.map(c => ({
+        index: c.index,
+        content: c.content,
+        charStart: c.charStart,
+        charEnd: c.charEnd,
+        embedding: new Float32Array(384),
+      }));
+    }),
+    prepareTextForEmbedding: vi.fn((title: string, tags: string[], content: string) => {
+      const tagLine = tags.length > 0 ? tags.join(", ") : "";
+      const parts = [title, tagLine, content].filter(p => p.length > 0);
+      return parts.join("\n");
+    }),
+  };
+});
 
-vi.mock("../embedder.js", () => ({
-  embed: vi.fn(async () => new Float32Array(384)),
-  prepareTextForEmbedding: vi.fn((title: string, tags: string[], content: string) => {
-    const tagLine = tags.length > 0 ? tags.join(", ") : "";
-    const parts = [title, tagLine, content].filter(p => p.length > 0);
-    return parts.join("\n").slice(0, 500);
-  }),
-}));
-
-import { embed } from "../embedder.js";
+import { embedDocument } from "../embedder.js";
 import { reindex } from "../reindex.js";
 import { KnowledgeDB } from "../db.js";
 
-const mockedEmbed = vi.mocked(embed);
+const mockedEmbed = vi.mocked(embedDocument);
 
 function makeDoc(title: string): string {
   return `---\ndate: 2026-03-24\ntype: research\nstatus: draft\n---\n\n# ${title}\n\nContent for ${title}.`;
@@ -353,4 +373,160 @@ describe("incremental reindex", () => {
     expect(results.some(r => r.id === "fresh-doc")).toBe(true);
     db1.close();
   });
+
+  it("scenario 13: 8K-char document produces >= 4 chunk rows", async () => {
+    const longBody = "A".repeat(8000);
+    writeFileSync(
+      join(dir, "long-doc.md"),
+      `---\ndate: 2026-03-24\ntype: research\nstatus: draft\n---\n\n# Long Doc\n\n${longBody}`,
+    );
+
+    await reindex([dir], dbPath);
+
+    const db = new KnowledgeDB(dbPath);
+    const row = db.db
+      .prepare("SELECT COUNT(*) as n FROM chunks WHERE document_id = ?")
+      .get("long-doc") as { n: number };
+    expect(row.n).toBeGreaterThanOrEqual(4);
+    db.close();
+  });
+
+  it("scenario 14: documents_vec row count equals total chunk count", async () => {
+    writeFileSync(join(dir, "doc-a.md"), makeDoc("Doc A"));
+    writeFileSync(join(dir, "doc-b.md"), makeDoc("Doc B"));
+    const longBody = "A".repeat(6000);
+    writeFileSync(
+      join(dir, "long-doc.md"),
+      `---\ndate: 2026-03-24\ntype: research\nstatus: draft\n---\n\n# Long Doc\n\n${longBody}`,
+    );
+
+    await reindex([dir], dbPath);
+
+    const db = new KnowledgeDB(dbPath);
+    // Instantiating VectorSearch loads sqlite-vec so documents_vec is queryable.
+    new VectorSearch(db).createIndex();
+    const chunksRow = db.db.prepare("SELECT COUNT(*) as n FROM chunks").get() as {
+      n: number;
+    };
+    const vecRow = db.db
+      .prepare("SELECT COUNT(*) as n FROM documents_vec")
+      .get() as { n: number };
+    expect(vecRow.n).toBe(chunksRow.n);
+    expect(chunksRow.n).toBeGreaterThanOrEqual(3); // at least one per doc
+    db.close();
+  });
+
+  it("scenario 15: chunk ids follow pattern {docId}#c{index}", async () => {
+    const longBody = "A".repeat(6000);
+    writeFileSync(
+      join(dir, "long-doc.md"),
+      `---\ndate: 2026-03-24\ntype: research\nstatus: draft\n---\n\n# Long Doc\n\n${longBody}`,
+    );
+
+    await reindex([dir], dbPath);
+
+    const db = new KnowledgeDB(dbPath);
+    new VectorSearch(db).createIndex();
+    const rows = db.db
+      .prepare("SELECT id, chunk_index FROM chunks WHERE document_id = ? ORDER BY chunk_index")
+      .all("long-doc") as Array<{ id: string; chunk_index: number }>;
+    expect(rows.length).toBeGreaterThan(1);
+    const idPattern = /^long-doc#c\d+$/;
+    for (const r of rows) {
+      expect(r.id).toMatch(idPattern);
+      expect(r.id).toBe(`long-doc#c${r.chunk_index}`);
+    }
+    // Verify documents_vec ids also follow the pattern for this doc.
+    const vecRows = db.db
+      .prepare("SELECT id FROM documents_vec WHERE id GLOB ?")
+      .all("long-doc#c*") as Array<{ id: string }>;
+    expect(vecRows.length).toBe(rows.length);
+    for (const v of vecRows) {
+      expect(v.id).toMatch(idPattern);
+    }
+    db.close();
+  });
+
+  it("scenario 16: deleting source file removes its chunks and vec rows", async () => {
+    const filePath = join(dir, "disposable.md");
+    const longBody = "A".repeat(6000);
+    writeFileSync(
+      filePath,
+      `---\ndate: 2026-03-24\ntype: research\nstatus: draft\n---\n\n# Disposable\n\n${longBody}`,
+    );
+    writeFileSync(join(dir, "keeper.md"), makeDoc("Keeper"));
+
+    await reindex([dir], dbPath);
+
+    const db1 = new KnowledgeDB(dbPath);
+    new VectorSearch(db1).createIndex();
+    const chunksBefore = db1.db
+      .prepare("SELECT COUNT(*) as n FROM chunks WHERE document_id = ?")
+      .get("disposable") as { n: number };
+    expect(chunksBefore.n).toBeGreaterThan(1);
+    const vecsBefore = db1.db
+      .prepare("SELECT COUNT(*) as n FROM documents_vec WHERE id GLOB ?")
+      .get("disposable#c*") as { n: number };
+    expect(vecsBefore.n).toBe(chunksBefore.n);
+    db1.close();
+
+    unlinkSync(filePath);
+    await reindex([dir], dbPath);
+
+    const db2 = new KnowledgeDB(dbPath);
+    new VectorSearch(db2).createIndex();
+    // Document gone -> chunks cascaded.
+    expect(db2.getDocument("disposable")).toBeUndefined();
+    const chunksAfter = db2.db
+      .prepare("SELECT COUNT(*) as n FROM chunks WHERE document_id = ?")
+      .get("disposable") as { n: number };
+    expect(chunksAfter.n).toBe(0);
+    // Vec rows for the deleted doc are gone (GLOB-based cleanup).
+    const vecsAfter = db2.db
+      .prepare("SELECT COUNT(*) as n FROM documents_vec WHERE id GLOB ?")
+      .get("disposable#c*") as { n: number };
+    expect(vecsAfter.n).toBe(0);
+    // The kept doc still has its chunks.
+    const keeperChunks = db2.db
+      .prepare("SELECT COUNT(*) as n FROM chunks WHERE document_id = ?")
+      .get("keeper") as { n: number };
+    expect(keeperChunks.n).toBeGreaterThanOrEqual(1);
+    db2.close();
+  });
+
+  it("scenario 17: re-indexing same file does not duplicate chunks", async () => {
+    const filePath = join(dir, "stable.md");
+    const body = "A".repeat(6000);
+    writeFileSync(
+      filePath,
+      `---\ndate: 2026-03-24\ntype: research\nstatus: draft\n---\n\n# Stable\n\n${body}`,
+    );
+
+    await reindex([dir], dbPath);
+    const db1 = new KnowledgeDB(dbPath);
+    const firstCount = (db1.db
+      .prepare("SELECT COUNT(*) as n FROM chunks WHERE document_id = ?")
+      .get("stable") as { n: number }).n;
+    db1.close();
+    expect(firstCount).toBeGreaterThan(1);
+
+    // Bump mtime to force re-embed.
+    const future = Date.now() / 1000 + 2;
+    utimesSync(filePath, future, future);
+
+    await reindex([dir], dbPath);
+    const db2 = new KnowledgeDB(dbPath);
+    new VectorSearch(db2).createIndex();
+    const secondCount = (db2.db
+      .prepare("SELECT COUNT(*) as n FROM chunks WHERE document_id = ?")
+      .get("stable") as { n: number }).n;
+    // Stale deletion before insert means chunk count stays the same, not 2x.
+    expect(secondCount).toBe(firstCount);
+    // And vec rows should match.
+    const vecCount = (db2.db
+      .prepare("SELECT COUNT(*) as n FROM documents_vec WHERE id GLOB ?")
+      .get("stable#c*") as { n: number }).n;
+    expect(vecCount).toBe(secondCount);
+    db2.close();
+  });
 });

package/src/__tests__/search.test.ts

@@ -205,6 +205,43 @@ describe("FtsSearch", () => {
     });
   });
 
+  describe("memory_tier filter", () => {
+    it("filters by memory_tier when schema has the column", () => {
+      db.db
+        .prepare("UPDATE documents SET memory_tier = ? WHERE id = ?")
+        .run("reflection", "auth-doc");
+      fts.rebuildIndex();
+
+      // auth-doc is "reflection", so search for terms in auth-doc should hit.
+      const reflectionHits = fts.search("authentication", { memoryTier: "reflection" });
+      const ids = reflectionHits.map((r) => r.id);
+      expect(ids).toContain("auth-doc");
+
+      // A "doc" filter should omit the reflection-tagged doc.
+      const docHits = fts.search("authentication", { memoryTier: "doc" });
+      expect(docHits.some((r) => r.id === "auth-doc")).toBe(false);
+    });
+
+    it("ignores memory_tier silently when column is absent (v2 schema)", () => {
+      // beforeEach gives us a v2 schema — column does not exist.
+      const results = fts.search("cache", { memoryTier: "reflection" });
+      // Filter is a no-op on v2; regular FTS results come through.
+      expect(Array.isArray(results)).toBe(true);
+    });
+
+    it("returns all tiers when memoryTier='any'", () => {
+      db.db
+        .prepare("UPDATE documents SET memory_tier = ? WHERE id = ?")
+        .run("reflection", "auth-doc");
+      fts.rebuildIndex();
+
+      const authHits = fts.search("authentication", { memoryTier: "any" });
+      expect(authHits.some((r) => r.id === "auth-doc")).toBe(true);
+      const cacheHits = fts.search("cache", { memoryTier: "any" });
+      expect(cacheHits.some((r) => r.id === "cache-doc")).toBe(true);
+    });
+  });
+
   describe("ensureTable", () => {
     it("creates FTS table if it does not exist", () => {
       // Create a fresh DB without FTS table

package/src/config.ts

@@ -0,0 +1,105 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/**
+ * Shape of the optional `~/.ralph/knowledge.config.json` file.
+ *
+ * All fields are optional. Unknown fields are preserved at parse time but are
+ * not surfaced through this interface — callers should treat the file as
+ * forward-compatible.
+ */
+export interface KnowledgeConfig {
+  /** Absolute or `~`-prefixed directories to index. */
+  roots?: string[];
+  /** Extra gitignore-syntax patterns layered on top of per-root `.ralphignore`. */
+  ignorePatterns?: string[];
+  /** Override for the SQLite database path. */
+  dbPath?: string;
+}
+
+/**
+ * Expand a leading `~` or `~/` segment in a path to the user's home directory.
+ * Paths that do not begin with `~` are returned unchanged.
+ */
+export function expandHome(p: string): string {
+  if (!p) return p;
+  if (p === "~") return homedir();
+  if (p.startsWith("~/") || p.startsWith("~\\")) {
+    return join(homedir(), p.slice(2));
+  }
+  return p;
+}
+
+/**
+ * Resolve the knowledge config file path. Precedence:
+ *   1. `process.env.RALPH_KNOWLEDGE_CONFIG`
+ *   2. `~/.ralph/knowledge.config.json`
+ */
+export function resolveConfigPath(): string {
+  const envPath = process.env.RALPH_KNOWLEDGE_CONFIG;
+  if (envPath && envPath.trim().length > 0) {
+    return expandHome(envPath);
+  }
+  return join(homedir(), ".ralph", "knowledge.config.json");
+}
+
+/**
+ * Load the optional `knowledge.config.json` file. Returns an empty object when
+ * the file is missing or malformed. Tilde-prefixed paths inside `roots` and
+ * `dbPath` are expanded eagerly so callers receive absolute paths.
+ */
+export function loadConfig(): KnowledgeConfig {
+  const configPath = resolveConfigPath();
+  if (!existsSync(configPath)) {
+    return {};
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(configPath, "utf-8");
+  } catch (e) {
+    console.warn(
+      `Failed to read knowledge config at ${configPath}: ${(e as Error).message}`,
+    );
+    return {};
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    console.warn(
+      `Malformed JSON in knowledge config at ${configPath}: ${(e as Error).message}`,
+    );
+    return {};
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    console.warn(
+      `Knowledge config at ${configPath} is not a JSON object; ignoring.`,
+    );
+    return {};
+  }
+
+  const obj = parsed as Record<string, unknown>;
+  const out: KnowledgeConfig = {};
+
+  if (Array.isArray(obj.roots)) {
+    out.roots = obj.roots
+      .filter((r): r is string => typeof r === "string" && r.length > 0)
+      .map(expandHome);
+  }
+
+  if (Array.isArray(obj.ignorePatterns)) {
+    out.ignorePatterns = obj.ignorePatterns.filter(
+      (p): p is string => typeof p === "string" && p.length > 0,
+    );
+  }
+
+  if (typeof obj.dbPath === "string" && obj.dbPath.length > 0) {
+    out.dbPath = expandHome(obj.dbPath);
+  }
+
+  return out;
+}

package/src/db.ts

@@ -468,6 +468,23 @@ export class KnowledgeDB {
     return row !== undefined;
   }
 
+  /**
+   * Returns the `memory_tier` for the given document id. Returns `undefined`
+   * when the document does not exist OR when the `memory_tier` column is
+   * absent from the schema (pre-v3 databases). Used by MCP `knowledge_*`
+   * tools that need to post-filter result sets by tier.
+   */
+  getMemoryTier(id: string): string | undefined {
+    const columns = this.db
+      .prepare("PRAGMA table_info(documents)")
+      .all() as Array<{ name: string }>;
+    if (!columns.some((c) => c.name === "memory_tier")) return undefined;
+    const row = this.db
+      .prepare("SELECT memory_tier AS memoryTier FROM documents WHERE id = ?")
+      .get(id) as { memoryTier: string } | undefined;
+    return row?.memoryTier;
+  }
+
   deleteDocument(id: string): void {
     this.db.prepare("DELETE FROM documents WHERE id = ?").run(id);
   }

package/src/embedder.ts

@@ -2,9 +2,9 @@ import {
   pipeline,
   type FeatureExtractionPipeline,
 } from "@huggingface/transformers";
+import { chunkText, type Chunk, type ChunkerOptions } from "./chunker.js";
 
 const MODEL_ID = "Xenova/all-MiniLM-L6-v2";
-const MAX_CHARS = 500;
 
 let embedderInstance: FeatureExtractionPipeline | null = null;
 
@@ -21,14 +21,71 @@ export async function getEmbedder(): Promise<FeatureExtractionPipeline> {
 
 export async function embed(text: string): Promise<Float32Array> {
   const embedder = await getEmbedder();
-  const truncated = text.slice(0, MAX_CHARS);
-  const output = await embedder(truncated, {
+  // Pass text directly — the transformer's own 512-token window handles overflow.
+  const output = await embedder(text, {
     pooling: "mean",
     normalize: true,
   });
   return new Float32Array(output.data as ArrayLike<number>);
 }
 
+/**
+ * A chunk paired with the embedding of its (contextualized) content.
+ * Extends the base Chunk from the chunker module with an embedding vector
+ * and an optional contextPrefix (populated by Phase 6 — contextual retrieval).
+ */
+export interface DocumentChunk extends Chunk {
+  embedding: Float32Array;
+  contextPrefix?: string;
+}
+
+/**
+ * Embed a document by splitting it into chunks and emitting one embedding
+ * per chunk. The embedded text for each chunk is
+ * `${title}\n${tagLine}\n${chunk.content}` so the semantic anchors (title +
+ * tags) travel with every chunk embedding — matching the shape of the legacy
+ * `prepareTextForEmbedding()` but without the 500-char truncation.
+ *
+ * Short documents (<= chunkSize) produce exactly one chunk covering the whole
+ * content. Empty content yields a single chunk with empty content (so callers
+ * still get a title/tag-only embedding for stub documents).
+ */
+export async function embedDocument(
+  title: string,
+  tags: string[],
+  content: string,
+  opts?: ChunkerOptions,
+): Promise<DocumentChunk[]> {
+  const tagLine = tags.length > 0 ? tags.join(", ") : "";
+
+  // If content is empty, still emit one chunk so the document has a searchable
+  // embedding anchored on title + tags (preserves legacy behavior for
+  // frontmatter-only / stub documents).
+  const chunks: Chunk[] = content.length === 0
+    ? [{ index: 0, content: "", charStart: 0, charEnd: 0 }]
+    : chunkText(content, opts);
+
+  const out: DocumentChunk[] = [];
+  for (const chunk of chunks) {
+    const parts = [title, tagLine, chunk.content].filter(p => p.length > 0);
+    const embedText = parts.join("\n");
+    const embedding = await embed(embedText);
+    out.push({
+      index: chunk.index,
+      content: chunk.content,
+      charStart: chunk.charStart,
+      charEnd: chunk.charEnd,
+      embedding,
+    });
+  }
+  return out;
+}
+
+/**
+ * Back-compat shim: kept so callers outside the reindex path can still build
+ * a title/tags/first-paragraph string. No longer used by `embedDocument` (the
+ * per-chunk flow prepends title + tags directly).
+ */
 export function prepareTextForEmbedding(
   title: string,
   tags: string[],
@@ -39,5 +96,5 @@ export function prepareTextForEmbedding(
   const paragraphs = content.split(/\n\n+/);
   const firstParagraph = paragraphs.find(p => p.trim().length > 0)?.trim() ?? "";
   const parts = [title, tagLine, firstParagraph].filter(p => p.length > 0);
-  return parts.join("\n").slice(0, MAX_CHARS);
+  return parts.join("\n");
 }

package/src/file-scanner.ts

@@ -1,14 +1,39 @@
 import { readdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, relative } from "node:path";
+import type { IgnoreMatcher } from "./ignore.js";
 
-export function findMarkdownFiles(dir: string): string[] {
+/**
+ * Recursively find all `.md` files under `dir`.
+ *
+ * Directory names beginning with `.` or `_` and file names beginning with `_`
+ * are always skipped (fast-path). When an {@link IgnoreMatcher} is supplied,
+ * each remaining path is additionally tested against it via its root-relative
+ * form; matches are skipped.
+ *
+ * @param dir root directory to walk
+ * @param matcher optional matcher built via `loadIgnoreForRoot(dir, …)`
+ */
+export function findMarkdownFiles(dir: string, matcher?: IgnoreMatcher): string[] {
   const results: string[] = [];
   function walk(d: string) {
     for (const entry of readdirSync(d, { withFileTypes: true })) {
       const fullPath = join(d, entry.name);
-      if (entry.isDirectory() && !entry.name.startsWith(".") && !entry.name.startsWith("_")) {
+      if (entry.isDirectory()) {
+        // Fast-path: hidden/underscored directories are always skipped.
+        if (entry.name.startsWith(".") || entry.name.startsWith("_")) continue;
+        if (matcher) {
+          // Test both bare and trailing-slash forms so gitignore-style
+          // directory-only patterns (e.g., `dist/`) match even when the
+          // directory itself has not yet been descended.
+          const rel = relative(dir, fullPath);
+          if (matcher.isIgnored(rel) || matcher.isIgnored(`${rel}/`)) continue;
+        }
         walk(fullPath);
       } else if (entry.isFile() && entry.name.endsWith(".md") && !entry.name.startsWith("_")) {
+        if (matcher) {
+          const rel = relative(dir, fullPath);
+          if (matcher.isIgnored(rel)) continue;
+        }
         results.push(fullPath);
       }
     }

package/src/hybrid-search.ts

@@ -4,6 +4,16 @@ import type { VectorSearch } from "./vector-search.js";
 
 export type EmbedFn = (text: string) => Promise<Float32Array>;
 
+interface ChunkRow {
+  id: string;
+  document_id: string;
+  chunk_index: number;
+  char_start: number;
+  char_end: number;
+  context_prefix: string;
+  content: string;
+}
+
 export class HybridSearch {
   private static readonly RRF_K = 60;
 
@@ -14,23 +24,64 @@ export class HybridSearch {
     private readonly embedFn: EmbedFn,
   ) {}
 
+  /**
+   * Returns true when the `chunks` table exists (schema v3+). When absent we
+   * behave as if all vector ids are doc ids (pre-chunking behavior).
+   */
+  private chunksTableExists(): boolean {
+    const row = this.db.db
+      .prepare(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name='chunks'",
+      )
+      .get();
+    return row !== undefined;
+  }
+
+  /**
+   * Given a vector-search id, return the `document_id` portion. Chunk ids
+   * follow the pattern `{doc_id}#c{index}` per Shared Constraint #6 of the
+   * GH-0761 plan. Legacy non-chunk ids pass through unchanged.
+   */
+  private docIdFromVecId(vecId: string): string {
+    const marker = vecId.lastIndexOf("#c");
+    if (marker === -1) return vecId;
+    const suffix = vecId.slice(marker + 2);
+    if (suffix.length === 0 || !/^\d+$/.test(suffix)) return vecId;
+    return vecId.slice(0, marker);
+  }
+
+  private fetchChunk(chunkId: string): ChunkRow | undefined {
+    if (!this.chunksTableExists()) return undefined;
+    return this.db.db
+      .prepare(
+        `SELECT id, document_id, chunk_index, char_start, char_end, context_prefix, content
+         FROM chunks WHERE id = ?`,
+      )
+      .get(chunkId) as ChunkRow | undefined;
+  }
+
   async search(
     query: string,
     options: SearchOptions = {},
   ): Promise<SearchResult[]> {
-    const { type, tags, includeSuperseded = false, limit = 20 } = options;
+    const { type, tags, includeSuperseded = false, limit = 20, memoryTier } = options;
 
-    // Run FTS and vector search
+    // Run FTS and vector search (FTS already applies memoryTier filter in SQL
+    // when the schema supports it).
     const ftsResults = this.fts.search(query, {
       includeSuperseded: true,
       limit: limit * 2,
+      memoryTier,
     });
 
     const queryEmbedding = await this.embedFn(query);
     const vecResults = this.vec.search(queryEmbedding, limit * 2);
 
-    // Build RRF score map
+    // Build RRF score map, keyed by document_id. When vec ids are chunk ids
+    // like `{doc}#c{n}`, we collapse to the parent doc for scoring but
+    // remember the best-scoring chunk id per doc for later meta enrichment.
     const scores = new Map<string, number>();
+    const bestChunkByDoc = new Map<string, { chunkId: string; rank: number }>();
 
     for (let i = 0; i < ftsResults.length; i++) {
       const id = ftsResults[i].id;
@@ -39,9 +90,16 @@ export class HybridSearch {
     }
 
     for (let i = 0; i < vecResults.length; i++) {
-      const id = vecResults[i].id;
+      const vecId = vecResults[i].id;
+      const docId = this.docIdFromVecId(vecId);
       const rrfScore = 1 / (HybridSearch.RRF_K + i + 1);
-      scores.set(id, (scores.get(id) ?? 0) + rrfScore);
+      scores.set(docId, (scores.get(docId) ?? 0) + rrfScore);
+      if (vecId !== docId) {
+        const existing = bestChunkByDoc.get(docId);
+        if (!existing || i < existing.rank) {
+          bestChunkByDoc.set(docId, { chunkId: vecId, rank: i });
+        }
+      }
     }
 
     // Build a lookup of FTS results by id for quick access
@@ -98,6 +156,31 @@ export class HybridSearch {
       });
     }
 
+    // Post-filter: memory_tier for vector-only hits that bypassed the FTS
+    // SQL filter. Also covers the case where the FTS stage returned 0 rows
+    // but vec returned chunks from a doc in another tier.
+    if (memoryTier && memoryTier !== "any") {
+      filtered = filtered.filter((r) => {
+        const tier = this.db.getMemoryTier(r.id);
+        // When column absent (v2 schema) treat as "doc"
+        return (tier ?? "doc") === memoryTier;
+      });
+    }
+
+    // Enrich with chunk meta when chunk data is available (best-scoring
+    // chunk per doc).
+    for (const r of filtered) {
+      const best = bestChunkByDoc.get(r.id);
+      if (!best) continue;
+      const chunk = this.fetchChunk(best.chunkId);
+      if (!chunk) continue;
+      r.bestChunkId = chunk.id;
+      r.chunkIndex = chunk.chunk_index;
+      r.charStart = chunk.char_start;
+      r.charEnd = chunk.char_end;
+      r.contextPrefix = chunk.context_prefix;
+    }
+
     return filtered.slice(0, limit);
   }
 }