obsidian-knowledge 3.19.0__py3-none-any.whl

lib/vault_index/__init__.py

@@ -0,0 +1,19 @@
+"""Shared retrieval + primer library for obsidian-knowledge plugin.
+
+Imported by both the Claude Code adapter (hooks/recall-init.py) and the
+Hermes Agent CLI memory provider (hermes-plugin/__init__.py).
+"""
+from lib.vault_index.config import VaultIndexConfig, load_config
+from lib.vault_index.filters import apply_filters, score_path
+from lib.vault_index.indexer import Hit, Indexer
+from lib.vault_index.primer import build_primer
+
+__all__ = [
+    "VaultIndexConfig",
+    "load_config",
+    "apply_filters",
+    "score_path",
+    "Hit",
+    "Indexer",
+    "build_primer",
+]

lib/vault_index/cli.py

@@ -0,0 +1,217 @@
+"""CLI entry points for obsidian-knowledge tooling."""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+import yaml
+
+DEFAULT_VAULT_INDEX_TEMPLATE = """
+# Vault index config — drives memweave retrieval, filtering, and weighting.
+# Path patterns are Python regexes evaluated against vault-relative paths.
+vault_index:
+  # What gets embedded at index time. Skipped paths are invisible to vault_search.
+  index:
+    allow_regex: []
+    deny_regex:
+      - "^Journal/"
+      - "^Inbox/"
+      - "^_sources/"
+      - "^\\\\.obsidian/"
+      - "^\\\\.config/"
+      - "^\\\\.stversions/"
+      - "^\\\\.trash/"
+      - "^Utility/obsidian-knowledge/cache/"
+
+  # What surfaces in default prefetch digest. Subset of indexed.
+  digest:
+    allow_regex:
+      - "^wiki/"
+      - "^.+/convos/"
+    deny_regex: []
+
+  # Score multipliers (longest-regex-match wins) applied before top-K truncation.
+  weights:
+    - regex: "^wiki/"
+      multiplier: 1.5
+    - regex: "^.+/convos/"
+      multiplier: 1.3
+    - regex: "^Utility/obsidian-knowledge/changelog/"
+      multiplier: 0.6
+
+  default_weight: 1.0
+  top_k: 5
+  # min_score: null  # uncomment to set a hard cutoff
+"""
+
+
+def init_vault_index(yaml_path: Path) -> None:
+    """Add a `vault_index:` section template to the per-vault config file.
+
+    No-op if the section already exists. Preserves any other sections.
+    """
+    if yaml_path.exists():
+        try:
+            existing = yaml.safe_load(yaml_path.read_text()) or {}
+        except yaml.YAMLError as exc:
+            print(f"error: malformed YAML in {yaml_path}: {exc}", file=sys.stderr)
+            sys.exit(1)
+        if "vault_index" in existing:
+            print(f"vault_index section already present in {yaml_path}; not modified.")
+            return
+        with yaml_path.open("a") as f:
+            f.write("\n" + DEFAULT_VAULT_INDEX_TEMPLATE)
+    else:
+        yaml_path.write_text(DEFAULT_VAULT_INDEX_TEMPLATE)
+    print(f"Wrote vault_index template to {yaml_path}")
+
+
+def link_hermes_memories(vault_root: Path, hermes_memories_dir: Path) -> None:
+    """Symlink Hermes built-in MEMORY.md and USER.md into the vault.
+
+    Symlinks live at <vault>/Utility/obsidian-knowledge/hermes/{MEMORY,USER}.md.
+    Idempotent — overwrites existing symlinks.
+
+    NOTE: Obsidian linter must be configured to skip this directory before
+    symlinks go live, or the linter's frontmatter rewrites will corrupt the
+    section-sign delimiter format Hermes uses. See:
+      <vault>/.obsidian/plugins/obsidian-linter/data.json (excluded_paths)
+    """
+    if not hermes_memories_dir.exists():
+        raise FileNotFoundError(f"Hermes memories dir not found: {hermes_memories_dir}")
+
+    link_dir = vault_root / "Utility" / "obsidian-knowledge" / "hermes"
+    link_dir.mkdir(parents=True, exist_ok=True)
+
+    for filename in ("MEMORY.md", "USER.md"):
+        target = hermes_memories_dir / filename
+        link = link_dir / filename
+        if not target.exists():
+            print(f"Source missing, skipping: {target}", file=sys.stderr)
+            continue
+        if link.is_symlink() or link.exists():
+            link.unlink()
+        link.symlink_to(target)
+        print(f"Symlinked: {link} -> {target}")
+
+    print(
+        f"\nIMPORTANT: configure your Obsidian linter to exclude '{link_dir.relative_to(vault_root)}/' "
+        "before opening these files in Obsidian. The linter would corrupt Hermes's "
+        "section-sign delimiter format otherwise."
+    )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="obsidian-knowledge")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_init = sub.add_parser(
+        "init-vault-index",
+        help="Add vault_index template to .claude/obsidian-knowledge.yaml",
+    )
+    p_init.add_argument("--vault", type=Path, default=Path.cwd(), help="Vault root (default: cwd)")
+
+    p_reindex = sub.add_parser("reindex", help="Run a full re-index of the vault")
+    p_reindex.add_argument("--vault", type=Path, default=Path.cwd())
+    p_reindex.add_argument("--force", action="store_true")
+
+    p_search = sub.add_parser("search", help="Hybrid (BM25+vector) search the vault index")
+    p_search.add_argument("query", help="Free-text query")
+    p_search.add_argument("--vault", type=Path, default=Path.cwd())
+    p_search.add_argument("--top-k", type=int, default=None)
+    p_search.add_argument(
+        "--all",
+        action="store_true",
+        help="Override digest filter (include paths normally hidden from prefetch).",
+    )
+
+    p_link = sub.add_parser(
+        "link-hermes-memories",
+        help="Symlink Hermes MEMORY.md/USER.md into the vault",
+    )
+    p_link.add_argument("--vault", type=Path, default=Path.cwd())
+    p_link.add_argument(
+        "--hermes-memories-dir",
+        type=Path,
+        default=Path.home() / ".hermes" / "memories",
+    )
+
+    args = parser.parse_args()
+
+    if args.cmd == "init-vault-index":
+        init_vault_index(args.vault / ".claude" / "obsidian-knowledge.yaml")
+    elif args.cmd == "reindex":
+        import fcntl
+        import memweave
+        from lib.vault_index.config import load_config
+        from lib.vault_index.indexer import Indexer, default_cache_dir
+
+        cfg = load_config(args.vault / ".claude" / "obsidian-knowledge.yaml")
+        cache = default_cache_dir(args.vault)
+        cache.mkdir(parents=True, exist_ok=True)
+        lock_path = cache / ".reindex.lock"
+        with open(lock_path, "w") as lock_f:
+            try:
+                fcntl.flock(lock_f.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except BlockingIOError:
+                print(
+                    "reindex: another reindex is in progress (lock held); exiting cleanly.",
+                    file=sys.stderr,
+                )
+                return 0
+            idx = Indexer(vault_root=args.vault, cache_dir=cache, config=cfg)
+            stats = idx.full_reindex(force=args.force)
+            print(
+                f"Indexed: {stats.indexed}, Skipped: {stats.skipped}, Deleted: {stats.deleted}",
+                flush=True,
+            )
+    elif args.cmd == "link-hermes-memories":
+        link_hermes_memories(args.vault, args.hermes_memories_dir)
+    elif args.cmd == "search":
+        from lib.vault_index.config import load_config
+        from lib.vault_index.indexer import Indexer, default_cache_dir
+
+        cfg = load_config(args.vault / ".claude" / "obsidian-knowledge.yaml")
+        cache = default_cache_dir(args.vault)
+        idx = Indexer(vault_root=args.vault, cache_dir=cache, config=cfg)
+        if not idx._vector_enabled:
+            print(f"# vector lane off ({idx.vector_status}); FTS-only", file=sys.stderr)
+        hits = idx.search(args.query, top_k=args.top_k, override_digest_filter=args.all)
+        if not hits:
+            print("(no results)")
+            return 0
+        for h in hits:
+            print(f"{h.score:6.1f}  {h.path}")
+
+    return 0
+
+
+def _exit_hard(code: int) -> None:
+    """Flush stdio then `os._exit` to skip Python's atexit/asyncio shutdown.
+
+    memweave/litellm/aiohttp leave non-daemon threads or pending tasks alive
+    after `idx.full_reindex()` and `idx.search()` finish, which makes the
+    interpreter hang on shutdown — confirmed on both dream-machine (Linux
+    Python 3.13) and mac mini (Apple Silicon Python 3.13), where the hourly
+    cron piled up zombie `reindex` processes overnight. Force-exit is the
+    same workaround used in `hermes_plugin` for the asyncio-daemon-thread
+    mismatch.
+
+    Called from `cli_main()` (the console-script entry point) so it applies
+    whether the CLI is invoked via `python -m lib.vault_index.cli` or via
+    the `obsidian-knowledge` entry point.
+    """
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os._exit(code)
+
+
+def cli_main() -> None:
+    """Console-script entry point. See [project.scripts] in pyproject.toml."""
+    _exit_hard(main())
+
+
+if __name__ == "__main__":
+    cli_main()

lib/vault_index/config.py

@@ -0,0 +1,44 @@
+"""Pydantic models + YAML loader for the vault_index config section."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field
+
+
+class IndexFilter(BaseModel):
+    allow_regex: list[str] = Field(default_factory=list)
+    deny_regex: list[str] = Field(default_factory=list)
+
+
+class DigestFilter(BaseModel):
+    allow_regex: list[str] = Field(default_factory=list)
+    deny_regex: list[str] = Field(default_factory=list)
+
+
+class WeightRule(BaseModel):
+    regex: str
+    multiplier: float
+
+
+class VaultIndexConfig(BaseModel):
+    index: IndexFilter = Field(default_factory=IndexFilter)
+    digest: DigestFilter = Field(default_factory=DigestFilter)
+    weights: list[WeightRule] = Field(default_factory=list)
+    default_weight: float = 1.0
+    top_k: int = 5
+    min_score: float | None = None
+
+
+def load_config(yaml_path: Path) -> VaultIndexConfig:
+    """Load `vault_index:` section from `<vault>/.claude/obsidian-knowledge.yaml`.
+
+    Returns defaults if the section is missing. Raises pydantic ValidationError
+    if the section is malformed.
+    """
+    if not yaml_path.exists():
+        return VaultIndexConfig()
+    raw = yaml.safe_load(yaml_path.read_text()) or {}
+    section = raw.get("vault_index", {}) or {}
+    return VaultIndexConfig.model_validate(section)

lib/vault_index/filters.py

@@ -0,0 +1,86 @@
+"""Path-based filtering and weighting."""
+from __future__ import annotations
+
+import re
+
+from lib.vault_index.config import DigestFilter, IndexFilter, VaultIndexConfig
+
+
+def score_path(path: str, config: VaultIndexConfig) -> float:
+    """Return the weight multiplier for `path` per config weights.
+
+    Longest regex match wins. Ties broken by first-listed rule.
+    Falls back to `default_weight` if no rule matches.
+    """
+    best_match_len = -1
+    best_multiplier = config.default_weight
+    for rule in config.weights:
+        m = re.search(rule.regex, path)
+        if m is None:
+            continue
+        match_len = m.end() - m.start()
+        if match_len > best_match_len:
+            best_match_len = match_len
+            best_multiplier = rule.multiplier
+    return best_multiplier
+
+
+def path_passes(path: str, filt: IndexFilter | DigestFilter) -> bool:
+    """Return True if `path` passes the allow/deny filter rules.
+
+    Logic:
+      - If `deny_regex` matches, fail.
+      - Else if `allow_regex` is non-empty, require a match.
+      - Else pass.
+    """
+    for pattern in filt.deny_regex:
+        if re.search(pattern, path):
+            return False
+    if filt.allow_regex:
+        return any(re.search(p, path) for p in filt.allow_regex)
+    return True
+
+
+def apply_filters(
+    hits: list,
+    config: VaultIndexConfig,
+    *,
+    override_digest_filter: bool = False,
+) -> list:
+    """Apply digest filters + path weights to a list of hits.
+
+    Pipeline:
+      1. (Unless overridden) drop hits failing the digest allow/deny.
+      2. Multiply each hit's score by its path weight.
+      3. Re-sort descending by weighted score.
+      4. Truncate to `config.top_k`.
+      5. (If `min_score` set) drop weighted scores below threshold.
+    """
+    from lib.vault_index.indexer import Hit
+
+    if not override_digest_filter:
+        hits = [h for h in hits if path_passes(h.path, config.digest)]
+
+    weighted: list[Hit] = []
+    for h in hits:
+        w = score_path(h.path, config)
+        weighted.append(Hit(
+            path=h.path,
+            score=h.score * w,
+            weight_applied=w,
+        ))
+
+    # Dedup by path — keep highest-scoring chunk per path so a note with
+    # multiple matching paragraphs doesn't crowd out other results.
+    best: dict[str, Hit] = {}
+    for h in weighted:
+        if h.path not in best or best[h.path].score < h.score:
+            best[h.path] = h
+    weighted = list(best.values())
+
+    weighted.sort(key=lambda h: h.score, reverse=True)
+
+    if config.min_score is not None:
+        weighted = [h for h in weighted if h.score >= config.min_score]
+
+    return weighted[: config.top_k]

lib/vault_index/indexer.py

@@ -0,0 +1,398 @@
+"""memweave wrapper for vault retrieval.
+
+Hybrid retrieval over a vault: BM25 (FTS5) + dense vectors (Ollama/local
+embeddings via LiteLLM), fused by memweave. Vector lane is on by default;
+the wrapper probes Ollama at construction and degrades to FTS-only if the
+embedding endpoint is unreachable or the chosen model isn't pulled.
+
+memweave API notes (verified against memweave source, 2026-05-09):
+- Main class is ``memweave.MemWeave`` (not ``memweave.Store``).
+- All public methods are async coroutines — wrapped here with asyncio.run().
+- File discovery uses ``workspace_dir/memory/`` + ``extra_paths``. We leave
+  ``workspace_dir/memory/`` empty and drive indexing entirely via
+  ``extra_paths`` (set to the filtered vault file list on each reindex).
+- Stored file paths are absolute. We convert to vault-relative on output.
+- ``IndexResult`` fields: ``files_indexed``, ``files_skipped``, ``files_deleted``.
+- ``status().files`` gives file count.
+- Deletion of stale files is handled by ``store.index()`` comparing
+  ``extra_paths`` to the DB's stored paths.
+- ``sync.on_search=True`` (memweave default) triggers an auto-reindex on every
+  search, which DELETES all stored chunks when extra_paths=[]. We always set
+  ``sync=SyncConfig(on_search=False)`` to prevent destructive auto-sync.
+- Search ``min_score`` defaults to 0.35 in memweave QueryConfig. We pass 0.0
+  and let ``apply_filters`` handle thresholding.
+
+Embedding defaults (this wrapper):
+- Model: ``ollama/bge-m3`` (8192-token context, multilingual, ~2.3GB).
+  Picked over mxbai-embed-large because mxbai's 512-token context overran
+  on long uninterrupted paragraphs (logged in changelog 2026-05-09).
+- API base: ``http://127.0.0.1:11434`` (Ollama default).
+- API key: empty placeholder (LiteLLM/Ollama doesn't require one).
+- Chunking: tokens=320, overlap=64 — well under bge-m3's 8192 ceiling, and
+  also safe if a user swaps in a 512-ctx model later.
+- Override any of the above via ``MEMWEAVE_EMBEDDING_MODEL``,
+  ``MEMWEAVE_EMBEDDING_API_BASE``, ``MEMWEAVE_EMBEDDING_API_KEY``.
+
+Fail-soft behavior: ``vector_enabled=True`` by default. On construction we do
+a quick HTTP probe of the Ollama tags endpoint; if it fails or the chosen
+model isn't listed, we silently flip vector off for this process and surface
+the reason via ``self.vector_status``. The doctor SessionStart hook reads
+the same probe and prints a one-line reminder.
+"""
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import os
+import re
+import urllib.error
+import urllib.request
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+import memweave
+import platformdirs
+from pydantic import BaseModel
+
+from lib.vault_index.config import VaultIndexConfig
+from lib.vault_index.filters import path_passes
+
+
+DEFAULT_EMBEDDING_MODEL = "ollama/bge-m3"
+DEFAULT_EMBEDDING_API_BASE = "http://127.0.0.1:11434"
+DEFAULT_CHUNK_TOKENS = 320
+DEFAULT_CHUNK_OVERLAP = 64
+PROBE_TIMEOUT_S = 1.5
+FINGERPRINT_FILENAME = "embedder-fingerprint.txt"
+APP_NAME = "obsidian-knowledge"
+
+
+def default_cache_dir(vault_root: Path) -> Path:
+    """Per-host, per-vault cache directory outside the vault.
+
+    Returns ``<XDG_CACHE_HOME or ~/.cache>/obsidian-knowledge/<vault-key>/``
+    on Linux and ``~/Library/Caches/obsidian-knowledge/<vault-key>/`` on macOS.
+    The vault-key combines the directory's basename with an 8-char hash of its
+    absolute path so two vaults with the same dir name (e.g. ``obsidian/``
+    on different machines or in different parents) never collide.
+
+    Storing the cache outside the vault eliminates the Syncthing-conflict risk
+    entirely: each host owns its own embeddings DB, no replication, no race.
+    """
+    abs_path = str(vault_root.resolve())
+    digest = hashlib.sha256(abs_path.encode()).hexdigest()[:8]
+    safe_name = re.sub(r"[^a-zA-Z0-9._-]", "-", vault_root.resolve().name) or "vault"
+    return Path(platformdirs.user_cache_dir(APP_NAME)) / f"{safe_name}-{digest}"
+
+
+def _ollama_probe(api_base: str, model: str) -> tuple[bool, str]:
+    """Check Ollama is up and the model is pulled. Returns (ok, message).
+
+    Strips the LiteLLM ``ollama/`` prefix from ``model`` before comparison
+    against Ollama's tag list. Tags appear as e.g. ``bge-m3:latest``; we
+    match on the bare name (everything before ``:``).
+    """
+    if not api_base.startswith("http"):
+        return False, f"api_base not http(s): {api_base}"
+    bare = model.split("/", 1)[1] if "/" in model else model
+    bare_name = bare.split(":", 1)[0]
+    url = api_base.rstrip("/") + "/api/tags"
+    try:
+        req = urllib.request.Request(url, headers={"Accept": "application/json"})
+        with urllib.request.urlopen(req, timeout=PROBE_TIMEOUT_S) as resp:
+            data = json.loads(resp.read())
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        return False, f"Ollama unreachable at {api_base}: {exc}"
+    except json.JSONDecodeError as exc:
+        return False, f"Ollama returned non-JSON: {exc}"
+    tags = [t.get("name", "") for t in data.get("models", [])]
+    if not any(name.split(":", 1)[0] == bare_name for name in tags):
+        return False, f"model '{bare_name}' not pulled (have: {tags or 'none'})"
+    return True, f"ok: {bare_name} via {api_base}"
+
+
+class Hit(BaseModel):
+    path: str
+    score: float
+    weight_applied: float = 1.0
+
+
+@dataclass
+class SyncStats:
+    indexed: int
+    skipped: int
+    deleted: int
+
+
+def _rescale(raw: float) -> float:
+    """Multiply raw BM25/hybrid score by 100 for readable digest display."""
+    return round(raw * 100, 1)
+
+
+
+
+class Indexer:
+    """Vault-aware wrapper around memweave.
+
+    Uses memweave's FTS5 (BM25) backend for keyword retrieval. Index-time
+    path filtering is applied by computing the allowed file list before each
+    ``index()`` call and passing it as ``extra_paths`` — files excluded by
+    config never enter the store.
+
+    All memweave calls are async internally; this class exposes a synchronous
+    interface via ``asyncio.run()``.
+
+    A single ``MemWeave`` instance is created at construction and reused for
+    all operations. ``full_reindex()`` closes and recreates it with updated
+    ``extra_paths`` so memweave's deletion detection sees exactly the
+    currently-allowed file set.
+    """
+
+    def __init__(
+        self,
+        vault_root: Path,
+        cache_dir: Path,
+        config: VaultIndexConfig,
+        *,
+        vector_enabled: bool = True,
+        skip_probe: bool = False,
+    ):
+        self.vault_root = vault_root
+        self.cache_dir = cache_dir
+        self.config = config
+        self._vector_enabled_requested = vector_enabled
+        self._vector_enabled = vector_enabled
+        self.vector_status = "disabled-by-caller"
+        cache_dir.mkdir(parents=True, exist_ok=True)
+
+        if vector_enabled and not skip_probe:
+            model, api_base, _ = self._embedding_settings()
+            ok, msg = _ollama_probe(api_base, model)
+            self.vector_status = msg
+            if not ok:
+                self._vector_enabled = False
+
+        # Lazy auto-rebuild flag: set to True if the stored embedder fingerprint
+        # differs from the current one. The next .search() or .full_reindex()
+        # call will trigger a force-rebuild before serving results.
+        self._needs_rebuild = self._stale_fingerprint() if self._vector_enabled else False
+
+        # Start with an empty-extra_paths store for read-only queries.
+        # full_reindex() will replace this with the full allowed-paths store.
+        self._store = memweave.MemWeave(
+            self._make_config(extra_paths=[])
+        )
+
+    def _embedder_fingerprint(self) -> str:
+        """Stable string identifying the current embedding setup.
+
+        Format: ``<model>@<chunk_tokens>/<chunk_overlap>``. Any change to
+        model name or chunking parameters invalidates the existing index
+        because chunk boundaries and vector dimensions may both shift.
+        """
+        model, _api_base, _ = self._embedding_settings()
+        return f"{model}@{DEFAULT_CHUNK_TOKENS}/{DEFAULT_CHUNK_OVERLAP}"
+
+    def _fingerprint_path(self) -> Path:
+        return self.cache_dir / FINGERPRINT_FILENAME
+
+    def _read_stored_fingerprint(self) -> str | None:
+        try:
+            return self._fingerprint_path().read_text().strip()
+        except OSError:
+            return None
+
+    def _write_fingerprint(self) -> None:
+        try:
+            self._fingerprint_path().write_text(self._embedder_fingerprint())
+        except OSError:
+            pass
+
+    def _stale_fingerprint(self) -> bool:
+        """True iff a populated index exists but was built with a different embedder.
+
+        We only consider the fingerprint stale when there is *something* to
+        invalidate — an empty cache or a never-indexed vault is a fresh install,
+        not a model swap, so we don't auto-rebuild on first run.
+        """
+        db = self.cache_dir / "index.sqlite"
+        if not db.exists():
+            return False
+        stored = self._read_stored_fingerprint()
+        if stored is None:
+            # Pre-3.15 cache: built FTS-only, no fingerprint. If vectors are
+            # enabled now, we need a rebuild to populate chunks_vec.
+            return True
+        return stored != self._embedder_fingerprint()
+
+    @staticmethod
+    def _embedding_settings() -> tuple[str, str, str | None]:
+        """Resolve (model, api_base, api_key) from env with bge-m3/Ollama defaults."""
+        model = os.environ.get("MEMWEAVE_EMBEDDING_MODEL", DEFAULT_EMBEDDING_MODEL)
+        api_base = os.environ.get(
+            "MEMWEAVE_EMBEDDING_API_BASE", DEFAULT_EMBEDDING_API_BASE
+        )
+        api_key = os.environ.get("MEMWEAVE_EMBEDDING_API_KEY")
+        return model, api_base, api_key
+
+    def _make_config(
+        self,
+        extra_paths: list[str],
+    ) -> memweave.MemoryConfig:
+        """Build a MemoryConfig for our vault-wrapper use case.
+
+        Key non-defaults:
+        - ``progress=False`` — suppress rich/spinner output.
+        - ``sync.on_search=False`` — prevent auto-reindex on search.
+        - ``vector.enabled`` — driven by the constructor-resolved value
+          (probe may have flipped it off).
+        - ``chunking`` — 320/64 (vs memweave default 400/80) so even a
+          512-token-context model can't overrun.
+        - ``embedding`` — defaults to ``ollama/bge-m3`` at
+          ``http://127.0.0.1:11434``. Override via ``MEMWEAVE_EMBEDDING_MODEL``,
+          ``MEMWEAVE_EMBEDDING_API_BASE``, ``MEMWEAVE_EMBEDDING_API_KEY``.
+        """
+        model, api_base, api_key = self._embedding_settings()
+        embedding_kwargs: dict = {"model": model, "api_base": api_base}
+        if api_key is not None:
+            embedding_kwargs["api_key"] = api_key
+
+        return memweave.MemoryConfig(
+            workspace_dir=str(self.cache_dir),
+            db_path=str(self.cache_dir / "index.sqlite"),
+            progress=False,
+            extra_paths=extra_paths,
+            embedding=memweave.EmbeddingConfig(**embedding_kwargs),
+            chunking=memweave.ChunkingConfig(
+                tokens=DEFAULT_CHUNK_TOKENS, overlap=DEFAULT_CHUNK_OVERLAP
+            ),
+            vector=memweave.VectorConfig(enabled=self._vector_enabled),
+            sync=memweave.SyncConfig(on_search=False),
+        )
+
+    def _abs_to_rel(self, abs_path: str) -> str:
+        """Convert an absolute path to vault-relative. Passthrough if outside vault."""
+        try:
+            return str(Path(abs_path).relative_to(self.vault_root))
+        except ValueError:
+            return abs_path
+
+    def row_count(self) -> int:
+        """Number of files currently indexed."""
+        status = asyncio.run(self._store.status())
+        return status.files
+
+    def indexed_paths(self) -> list[str]:
+        """All currently-indexed paths, relative to vault_root."""
+        files = asyncio.run(self._store.files())
+        return [self._abs_to_rel(f.path) for f in files]
+
+    def _allowed_vault_files(self) -> list[str]:
+        """Return absolute paths of all vault .md files passing index filters."""
+        allowed = []
+        for abs_path in self.vault_root.rglob("*.md"):
+            rel = str(abs_path.relative_to(self.vault_root))
+            if path_passes(rel, self.config.index):
+                allowed.append(str(abs_path))
+        return allowed
+
+    def full_reindex(self, force: bool = False) -> SyncStats:
+        """Walk vault, index every markdown file matching index filters.
+
+        Closes the current MemWeave instance and creates a new one with
+        ``extra_paths`` set to the filtered file list. memweave's ``index()``
+        handles hash-skip logic (unchanged files are skipped unless
+        ``force=True``) and automatic deletion of stale DB entries (paths
+        previously in the DB that are no longer in ``extra_paths``).
+
+        Writes the embedder fingerprint after a successful run so the next
+        Indexer init can detect a model change and auto-rebuild.
+        """
+        # Close the current store before opening a new one on the same DB.
+        asyncio.run(self._store.close())
+
+        allowed = self._allowed_vault_files()
+        self._store = memweave.MemWeave(
+            self._make_config(extra_paths=allowed)
+        )
+        result = asyncio.run(self._store.index(force=force))
+        self._write_fingerprint()
+        self._needs_rebuild = False
+        return SyncStats(
+            indexed=result.files_indexed,
+            skipped=result.files_skipped,
+            deleted=result.files_deleted,
+        )
+
+    def _auto_rebuild(self, reason: str) -> None:
+        """Force-rebuild the index, printing a notice. Used for embedder swaps."""
+        import sys
+        stored = self._read_stored_fingerprint() or "none"
+        current = self._embedder_fingerprint()
+        print(
+            f"# vault-index: rebuilding ({reason}; was {stored}, now {current})",
+            file=sys.stderr,
+            flush=True,
+        )
+        self.full_reindex(force=True)
+
+    def sync(self) -> SyncStats:
+        """Incremental re-index. Same as full_reindex without force."""
+        return self.full_reindex(force=False)
+
+    def search(
+        self,
+        query: str,
+        *,
+        top_k: int | None = None,
+        min_score: float | None = None,
+        override_digest_filter: bool = False,
+    ) -> list[Hit]:
+        """Run FTS retrieval; apply digest filter + weights; rescale; truncate.
+
+        Always passes ``min_score=0.0`` to memweave so the default 0.35
+        threshold (which filters out short-document BM25 scores) doesn't
+        silently drop results. Score thresholding is applied by ``apply_filters``
+        using ``config.min_score``.
+        """
+        from lib.vault_index.filters import apply_filters
+
+        effective_top_k = top_k or self.config.top_k
+        # Request more candidates than needed so apply_filters has room to filter.
+        candidate_count = max(50, effective_top_k * 5)
+
+        # Auto-rebuild when the embedder fingerprint changed since the last
+        # successful index. This keeps "swap MEMWEAVE_EMBEDDING_MODEL and run
+        # /vault-search" from blowing up on a stale chunks_vec.
+        if self._needs_rebuild:
+            self._auto_rebuild(reason="embedder changed")
+
+        try:
+            raw = asyncio.run(
+                self._store.search(query, max_results=candidate_count, min_score=0.0)
+            )
+        except memweave.SearchError as exc:
+            # Defensive net: reindex didn't run for some reason but the index
+            # is missing chunks_vec. Trigger a rebuild and retry once.
+            if "chunks_vec" in str(exc) and self._vector_enabled:
+                self._auto_rebuild(reason="chunks_vec missing")
+                raw = asyncio.run(
+                    self._store.search(
+                        query, max_results=candidate_count, min_score=0.0
+                    )
+                )
+            else:
+                raise
+        hits = [
+            Hit(path=self._abs_to_rel(r.path), score=_rescale(r.score), weight_applied=1.0)
+            for r in raw
+        ]
+
+        cfg = self.config
+        if top_k is not None:
+            cfg = cfg.model_copy(update={"top_k": top_k})
+        if min_score is not None:
+            cfg = cfg.model_copy(update={"min_score": min_score})
+
+        return apply_filters(hits, cfg, override_digest_filter=override_digest_filter)

lib/vault_index/primer.py

@@ -0,0 +1,58 @@
+"""Harness primer text. Single source of truth for both CC and Hermes adapters."""
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def _resolve_memory_target(cwd: str):
+    """Lazy import; the resolver lives under hooks/ which isn't always on path."""
+    plugin_root = Path(__file__).resolve().parent.parent.parent
+    hooks_dir = plugin_root / "hooks"
+    if str(hooks_dir) not in sys.path:
+        sys.path.insert(0, str(hooks_dir))
+    from hookslib.repo_memory import resolve_target  # noqa: WPS433
+    return resolve_target(cwd)
+
+
+def build_primer(
+    vault_root: Path,
+    plugin_root: Path,
+    cwd: str | None = None,
+) -> str:
+    """Build the harness primer text injected into every session.
+
+    Loaded into every session's context. Must stand alone — agents that
+    read only this primer should know what to do.
+
+    `cwd` (optional) lets the primer surface the *exact* per-repo or per-host
+    memory directory the agent should write to. Defaults to os.getcwd().
+    """
+    wiki = vault_root / "wiki"
+    target = _resolve_memory_target(cwd or os.getcwd())
+    memory_dir = wiki / target.rel_path
+    if target.kind == "repo":
+        scope_desc = f"this repo ({target.owner}/{target.repo})"
+    else:
+        scope_desc = f"this host ({target.hostname}) — cwd is not in a git repo"
+    return (
+        "You are operating under the obsidian-knowledge harness.\n"
+        f"- Knowledge: Obsidian wiki at {wiki}/ is the persistent memory store — "
+        "search it before answering non-trivial questions with `/vault-search <query>` "
+        "(hybrid BM25 + dense-embedding retrieval; ranked top-K paths). "
+        f"Fall back to `rg <pattern> {wiki}/` only for exact-string lookups. "
+        "File outcomes at session end (`remember-conversations` skill) — this creates a terse changelog entry and any diary/convo notes. "
+        "Do NOT use Claude's built-in MEMORY.md system; the wiki is the source of truth.\n"
+        f"- Per-session agent memory ({scope_desc}) lives at "
+        f"{memory_dir}/. Use the same MEMORY.md + per-fact .md file layout as "
+        "Claude's native auto-memory, but stored in the vault so it's portable, "
+        "syncs across hosts, and is searchable. Read MEMORY.md there at session "
+        "start; append new feedback/project/reference facts there, not under "
+        "~/.claude/projects/*/memory/ (a PreToolUse hook will block that).\n"
+        "- Reflect on friction: if you struggle with the harness, hit unexpected "
+        "blocks, or repeat the same workaround, invoke `/improve-harness`.\n"
+        "- Reflect on user frustration: if the user expresses frustration "
+        "('fuck', 'wtf', 'this keeps happening'), invoke `/improve-harness`. "
+        "The agent is not the unit of analysis — the system is."
+    )

obsidian_knowledge-3.19.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: obsidian-knowledge
+Version: 3.19.0
+Summary: Obsidian vault knowledge integration for Claude Code and Hermes Agent CLI
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: memweave>=0.1
+Requires-Dist: platformdirs>=4.9.6
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0

obsidian_knowledge-3.19.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+lib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lib/vault_index/__init__.py,sha256=CAoRrkN4hqEDke4QiL0NSEDp94VdylIjknKvXc2KHfA,574
+lib/vault_index/cli.py,sha256=NhGFYbzdB4Jwm3ZZotXTEjfmX8llyWvqoHc0Ck1GQt8,7985
+lib/vault_index/config.py,sha256=-lqrwZskSWhvsG5XbmlE9fsLe3_1qAUpxHozVJwVuPA,1328
+lib/vault_index/filters.py,sha256=6Pl2DkkWmisOSUasLDX48aG4HPJdKUiuPWCzRSm3p7I,2662
+lib/vault_index/indexer.py,sha256=gYR8asRyqgWmRWnx-RlT_pjZ7Dj1RbpAl3CBgn-4-1s,16455
+lib/vault_index/primer.py,sha256=3XExEozDaSAcyWOVvgDtMl9EHK2W3_lEfVSeSQiKBLE,2834
+obsidian_knowledge-3.19.0.dist-info/METADATA,sha256=FSerM37BT4Oxs_MwknaDRgVjBrlnLeJGbKhzcJ5eRfc,312
+obsidian_knowledge-3.19.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+obsidian_knowledge-3.19.0.dist-info/entry_points.txt,sha256=hD9HHnEfFRRRHSpfydJ6JncPK99Gfd0keXvnX-p-GQQ,68
+obsidian_knowledge-3.19.0.dist-info/licenses/LICENSE,sha256=cmlMn4TweDeX2VOmTt41lUJZplQlVBO8e5bjLKLzz-M,1071
+obsidian_knowledge-3.19.0.dist-info/RECORD,,

obsidian_knowledge-3.19.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

obsidian_knowledge-3.19.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+obsidian-knowledge = lib.vault_index.cli:cli_main

obsidian_knowledge-3.19.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Ricardo Decal
+
+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.
+