fix: change from doc hash to path hash

Author: saccharin98

openkb/agent/compiler.py

@@ -538,10 +538,13 @@ def _update_index(
     lines = index_path.read_text(encoding="utf-8").split("\n")
 
     doc_link = f"[[summaries/{doc_name}]]"
-    if not _section_contains_link(lines, "## Documents", doc_link):
-        doc_entry = f"- {doc_link} ({doc_type})"
+    doc_entry = f"- {doc_link} ({doc_type})"
+    if doc_brief:
+        doc_entry += f" — {doc_brief}"
+    if _section_contains_link(lines, "## Documents", doc_link):
         if doc_brief:
-            doc_entry += f" — {doc_brief}"
+            _replace_section_entry(lines, "## Documents", doc_link, doc_entry)
+    else:
         _insert_section_entry(lines, "## Documents", doc_entry)
 
     for name in concept_names:

openkb/cli.py

@@ -20,7 +20,7 @@
 from dotenv import load_dotenv
 
 from openkb.config import DEFAULT_CONFIG, load_config, save_config, load_global_config, register_kb
-from openkb.converter import convert_document
+from openkb.converter import _registry_path, convert_document
 from openkb.log import append_log
 from openkb.schema import AGENTS_MD
 
@@ -202,11 +202,18 @@ def _add_single_file(file_path: Path, kb_dir: Path) -> None:
     # Register hash only after successful compilation
     if result.file_hash:
         doc_type = "long_pdf" if result.is_long_doc else file_path.suffix.lstrip(".")
-        registry.add(result.file_hash, {
+        metadata = {
             "name": file_path.name,
             "doc_name": doc_name,
             "type": doc_type,
-        })
+            "path": _registry_path(file_path, kb_dir),
+        }
+        if result.raw_path is not None:
+            metadata["raw_path"] = _registry_path(result.raw_path, kb_dir)
+        if result.source_path is not None:
+            metadata["source_path"] = _registry_path(result.source_path, kb_dir)
+        registry.remove_by_doc_name(doc_name)
+        registry.add(result.file_hash, metadata)
 
     append_log(kb_dir / "wiki", "ingest", file_path.name)
     click.echo(f"  [OK] {file_path.name} added to knowledge base.")

openkb/converter.py

@@ -1,6 +1,7 @@
 """Document conversion pipeline for OpenKB."""
 from __future__ import annotations
 
+import hashlib
 import logging
 import re
 import shutil
@@ -31,16 +32,31 @@ class ConvertResult:
 
 
 _SAFE_STEM_RE = re.compile(r"[^\w\-]+")
-_DOC_HASH_LEN = 10
+_DOC_HASH_LEN = 12
 
 
-def _make_doc_name(src: Path, file_hash: str) -> str:
+def _registry_path(path: Path, kb_dir: Path) -> str:
+    """Return the portable path key stored in the hash registry."""
+    resolved_path = path.resolve()
+    resolved_kb = kb_dir.resolve()
+    if resolved_path.is_relative_to(resolved_kb):
+        return resolved_path.relative_to(resolved_kb).as_posix()
+    return resolved_path.as_posix()
+
+
+def _path_hash(src: Path, kb_dir: Path) -> str:
+    """Return a stable hash for a source path, independent of file content."""
+    identity = _registry_path(src, kb_dir)
+    return hashlib.sha256(identity.encode("utf-8")).hexdigest()
+
+
+def _make_doc_name(src: Path, kb_dir: Path) -> str:
     """Return the stable internal document name for a source file."""
     stem = unicodedata.normalize("NFKC", src.stem)
     safe_stem = _SAFE_STEM_RE.sub("-", stem).strip("-")
     if not safe_stem:
         safe_stem = "document"
-    return f"{safe_stem}-{file_hash[:_DOC_HASH_LEN]}"
+    return f"{safe_stem}-{_path_hash(src, kb_dir)[:_DOC_HASH_LEN]}"
 
 
 def get_pdf_page_count(path: Path) -> int:
@@ -53,7 +69,7 @@ def convert_document(src: Path, kb_dir: Path) -> ConvertResult:
     """Convert a document and integrate it into the knowledge base.
 
     Steps:
-    1. Hash-check — skip if already known.
+    1. Hash-check — skip if this exact content is already known.
     2. Copy source to ``raw/``.
     3. If PDF and page count >= threshold → return :attr:`ConvertResult.is_long_doc`.
     4. If ``.md`` — read, process relative images, save to ``wiki/sources/``.
@@ -72,14 +88,16 @@ def convert_document(src: Path, kb_dir: Path) -> ConvertResult:
     # 1. Hash check
     # ------------------------------------------------------------------
     file_hash = HashRegistry.hash_file(src)
-    doc_name = _make_doc_name(src, file_hash)
+    path_key = _registry_path(src, kb_dir)
+    path_metadata = registry.get_by_path(path_key) or {}
+    doc_name = path_metadata.get("doc_name") or _make_doc_name(src, kb_dir)
     if registry.is_known(file_hash):
         logger.info("Skipping already-known file: %s", src.name)
         metadata = registry.get(file_hash) or {}
         return ConvertResult(
             skipped=True,
             file_hash=file_hash,
-            doc_name=metadata.get("doc_name", doc_name),
+            doc_name=metadata.get("doc_name") or doc_name,
         )
 
     # ------------------------------------------------------------------

openkb/state.py

@@ -32,6 +32,13 @@ def all_entries(self) -> dict[str, dict]:
         """Return a shallow copy of all hash -> metadata entries."""
         return dict(self._data)
 
+    def get_by_path(self, path: str) -> dict | None:
+        """Return metadata for a registered raw/source path, if present."""
+        for metadata in self._data.values():
+            if metadata.get("raw_path") == path or metadata.get("source_path") == path:
+                return metadata
+        return None
+
     # ------------------------------------------------------------------
     # Mutation
     # ------------------------------------------------------------------
@@ -41,6 +48,19 @@ def add(self, file_hash: str, metadata: dict) -> None:
         self._data[file_hash] = metadata
         self._persist()
 
+    def remove_by_doc_name(self, doc_name: str) -> None:
+        """Remove stale content-hash entries for a document identity."""
+        stale_hashes = [
+            file_hash
+            for file_hash, metadata in self._data.items()
+            if metadata.get("doc_name") == doc_name
+        ]
+        if not stale_hashes:
+            return
+        for file_hash in stale_hashes:
+            del self._data[file_hash]
+        self._persist()
+
     # ------------------------------------------------------------------
     # Internal
     # ------------------------------------------------------------------

openkb/watcher.py

@@ -53,11 +53,11 @@ def _flush(self) -> None:
         if paths:
             self._callback(paths)
 
-    def _handle_event(self, event) -> None:
-        """Add the event's source path to pending if it's a supported file."""
+    def _handle_event(self, event, path_attr: str = "src_path") -> None:
+        """Add the event path to pending if it's a supported file."""
         if event.is_directory:
             return
-        path = Path(event.src_path)
+        path = Path(getattr(event, path_attr))
         # Ignore hidden/dotfiles
         if path.name.startswith("."):
             return
@@ -73,6 +73,10 @@ def on_modified(self, event) -> None:
         """Handle file modification events."""
         self._handle_event(event)
 
+    def on_moved(self, event) -> None:
+        """Handle atomic-save and rename events."""
+        self._handle_event(event, "dest_path")
+
 
 def watch_directory(
     raw_dir: Path,

tests/test_add_command.py

@@ -143,6 +143,11 @@ def test_add_short_doc_runs_compiler(self, tmp_path):
             is_long_doc=False,
             file_hash="deadbeef00" * 8,
         )
+        stale_hash = "oldhash"
+        hashes_path = kb_dir / ".openkb" / "hashes.json"
+        hashes_path.write_text(json.dumps({
+            stale_hash: {"name": "test.md", "doc_name": mock_result.doc_name, "type": "md"}
+        }))
 
         runner = CliRunner()
         with patch("openkb.cli._find_kb_dir", return_value=kb_dir), \
@@ -153,4 +158,7 @@ def test_add_short_doc_runs_compiler(self, tmp_path):
             assert "OK" in result.output
 
         hashes = json.loads((kb_dir / ".openkb" / "hashes.json").read_text())
+        assert stale_hash not in hashes
         assert hashes[mock_result.file_hash]["doc_name"] == "test-deadbeef00"
+        assert hashes[mock_result.file_hash]["raw_path"] == "raw/test.md"
+        assert hashes[mock_result.file_hash]["source_path"] == "wiki/sources/test.md"

tests/test_compiler.py

@@ -228,6 +228,8 @@ def test_no_duplicates(self, tmp_path):
         _update_index(wiki, "my-doc", [], doc_brief="New brief")
         text = (wiki / "index.md").read_text()
         assert text.count("[[summaries/my-doc]]") == 1
+        assert "- [[summaries/my-doc]] (short) — New brief" in text
+        assert "Old brief" not in text
 
     def test_backwards_compat_no_briefs(self, tmp_path):
         wiki = tmp_path / "wiki"

tests/test_converter.py

@@ -7,7 +7,7 @@
 
 import pytest
 
-from openkb.converter import ConvertResult, convert_document, get_pdf_page_count
+from openkb.converter import ConvertResult, _make_doc_name, convert_document, get_pdf_page_count
 
 
 # ---------------------------------------------------------------------------
@@ -42,12 +42,27 @@ def test_md_file_copied_to_wiki_sources(self, kb_dir):
 
         assert result.skipped is False
         assert result.is_long_doc is False
-        assert result.doc_name == f"notes-{result.file_hash[:10]}"
+        assert result.doc_name == _make_doc_name(src, kb_dir)
         assert result.source_path is not None
         assert result.source_path.name == f"{result.doc_name}.md"
         assert result.source_path.exists()
         assert result.source_path.read_text(encoding="utf-8").startswith("# Notes")
 
+    def test_md_file_keeps_doc_name_when_content_changes(self, kb_dir):
+        """A raw file keeps the same document identity across edits."""
+        src = kb_dir / "raw" / "notes.md"
+        src.write_text("# Notes\n\nOld content.", encoding="utf-8")
+
+        first_result = convert_document(src, kb_dir)
+        src.write_text("# Notes\n\nNew content.", encoding="utf-8")
+        second_result = convert_document(src, kb_dir)
+
+        assert second_result.skipped is False
+        assert second_result.file_hash != first_result.file_hash
+        assert second_result.doc_name == first_result.doc_name
+        assert second_result.source_path == first_result.source_path
+        assert second_result.source_path.read_text(encoding="utf-8").startswith("# Notes\n\nNew content.")
+
     def test_md_duplicate_skipped(self, kb_dir):
         """Second call with same file returns skipped=True when hash is registered."""
         from openkb.state import HashRegistry

tests/test_state.py

@@ -53,6 +53,30 @@ def test_all_entries_empty(tmp_path):
     assert registry.all_entries() == {}
 
 
+def test_get_by_path_matches_raw_or_source_path(tmp_path):
+    registry = HashRegistry(tmp_path / "hashes.json")
+    metadata = {
+        "doc_name": "paper-abc123",
+        "raw_path": "raw/paper.pdf",
+        "source_path": "wiki/sources/paper.md",
+    }
+    registry.add("hash1", metadata)
+
+    assert registry.get_by_path("raw/paper.pdf") == metadata
+    assert registry.get_by_path("wiki/sources/paper.md") == metadata
+
+
+def test_remove_by_doc_name_deletes_stale_hash_entries(tmp_path):
+    registry = HashRegistry(tmp_path / "hashes.json")
+    registry.add("old", {"doc_name": "paper-abc123"})
+    registry.add("other", {"doc_name": "other-def456"})
+
+    registry.remove_by_doc_name("paper-abc123")
+
+    assert registry.is_known("old") is False
+    assert registry.is_known("other") is True
+
+
 def test_hash_file_produces_64_char_hex(tmp_path):
     f = tmp_path / "sample.txt"
     f.write_text("hello world")

tests/test_watcher.py

@@ -16,6 +16,13 @@ def _make_file_event(src_path: str, is_directory: bool = False):
     return event
 
 
+def _make_moved_event(src_path: str, dest_path: str, is_directory: bool = False):
+    """Create a mock watchdog move event."""
+    event = _make_file_event(src_path, is_directory=is_directory)
+    event.dest_path = dest_path
+    return event
+
+
 class TestDebouncedHandler:
     def test_collects_created_files(self):
         callback = MagicMock()
@@ -42,6 +49,17 @@ def test_collects_modified_files(self):
 
         assert "/raw/paper.txt" in handler._pending
 
+    def test_collects_moved_destination_file(self):
+        callback = MagicMock()
+        handler = DebouncedHandler(callback, debounce_seconds=100)
+
+        handler.on_moved(_make_moved_event("/raw/.notes.md.tmp", "/raw/notes.md"))
+
+        if handler._timer:
+            handler._timer.cancel()
+
+        assert handler._pending == {"/raw/notes.md"}
+
     def test_ignores_directories(self):
         callback = MagicMock()
         handler = DebouncedHandler(callback, debounce_seconds=100)