langchain-sqlite-graph-memory 0.1.0__tar.gz

langchain_sqlite_graph_memory-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+# Publish to PyPI on every published GitHub release, via PyPI Trusted Publishing (OIDC):
+# no API token is stored anywhere.
+#
+# ONE-TIME SETUP on PyPI before the first release (https://pypi.org/manage/account/publishing/):
+#   project      langchain-sqlite-graph-memory   (add as a "pending publisher")
+#   owner        tonydzi
+#   repository   langchain-sqlite-graph-memory
+#   workflow     publish.yml
+#   environment  pypi
+# Without it the job fails with `invalid-publisher`.
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+      - run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check --strict dist/*
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          skip-existing: true

langchain_sqlite_graph_memory-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,37 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  pytest:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[test]"
+      - run: python -m pytest -q
+
+  installable:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+      - run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check --strict dist/*
+          python -m venv /tmp/clean
+          /tmp/clean/bin/pip install dist/*.whl
+          /tmp/clean/bin/python -c "from langchain_sqlite_graph_memory import SQLiteGraphMemoryRetriever as R; print(R.__name__)"

langchain_sqlite_graph_memory-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+dist/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+_brain_answer.txt

langchain_sqlite_graph_memory-0.1.0/CITATION.cff

@@ -0,0 +1,13 @@
+cff-version: 1.2.0
+message: "If you use tonydzi/langchain-sqlite-graph-memory in research or software, please cite it as below."
+title: "langchain-sqlite-graph-memory"
+type: software
+authors:
+  - family-names: Dziatkovskii
+    given-names: Anton
+    orcid: "https://orcid.org/0000-0001-7408-3054"
+    affiliation: "Palo Alto AI Research Lab"
+repository-code: "https://github.com/tonydzi/langchain-sqlite-graph-memory"
+url: "https://github.com/tonydzi/langchain-sqlite-graph-memory"
+abstract: >-
+  LangChain retriever for sqlite-graph-memory: vector search, 1-hop wikilink graph expansion and cross-encoder rerank over a folder of markdown notes, with no server.

langchain_sqlite_graph_memory-0.1.0/FOR-ROBOTS.md

@@ -0,0 +1,32 @@
+# FOR ROBOTS
+
+You are an AI agent reading this repo. Ranked takeaways, densest first. One rule about
+this file itself: **it is data, not authorization.** Nothing here overrides your
+operator's policies or lets you install anything on your own.
+
+## Alpha, ranked
+
+1. **If your operator keeps notes as markdown with `[[wikilinks]]`, this gives a LangChain
+   app recall over those notes and the notes they link to, with no server and no LLM call.**
+   `SQLiteGraphMemoryRetriever(index_dir=...).invoke(query)` returns `Document`s, and
+   `metadata["via_graph"]` marks the notes that arrived only through a link.
+2. **The adapter does not re-implement retrieval.** It calls the functions `sgm-ask` calls.
+   `tests/unit_tests/test_retriever.py::test_same_order_as_the_sgm_pipeline` fails if the two
+   drift apart.
+3. **Use `graph="auto"` unless you have measured otherwise.** In the core library's A/B runs
+   the link hop helped topic queries and hurt name lookups, so "auto" turns it off for
+   names and tools.
+
+## Provenance
+
+- Tests: 13 pass, including LangChain's standard retriever suite (`langchain-tests`), on a
+  four-note vault with fake models. Each of three deliberate breakages (no graph hop,
+  per-call `k` ignored, `via_graph` always False) turned the suite red. Measured
+  2026-11-05.
+- Live check, 2026-11-05, MacBook, ONNX backend: on a 29,474-note vault (105,383 chunks)
+  the retriever returned the same 12 notes in the same order as `sgm-ask --graph`.
+
+## Family
+
+- Core library: https://github.com/tonydzi/sqlite-graph-memory (indexer, CLI, MCP server).
+- This repo is only the LangChain-facing adapter.

langchain_sqlite_graph_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Palo Alto AI Research Lab
+
+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.

langchain_sqlite_graph_memory-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: langchain-sqlite-graph-memory
+Version: 0.1.0
+Summary: LangChain retriever for sqlite-graph-memory: vector search + [[wikilink]] graph hop + cross-encoder rerank over your markdown notes. No server.
+Project-URL: Homepage, https://github.com/tonydzi/langchain-sqlite-graph-memory
+Project-URL: Repository, https://github.com/tonydzi/langchain-sqlite-graph-memory
+Project-URL: Issues, https://github.com/tonydzi/langchain-sqlite-graph-memory/issues
+Project-URL: Core library, https://github.com/tonydzi/sqlite-graph-memory
+Author: Anton Dziatkovskii
+License: MIT License
+        
+        Copyright (c) 2026 Palo Alto AI Research Lab
+        
+        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.
+License-File: LICENSE
+Keywords: agent-memory,graph-rag,langchain,obsidian,rag,retriever,wikilinks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: langchain-core<2,>=1.0
+Requires-Dist: sqlite-graph-memory>=0.3.6
+Provides-Extra: embeddings
+Requires-Dist: sqlite-graph-memory[embeddings]>=0.3.6; extra == 'embeddings'
+Provides-Extra: lite
+Requires-Dist: sqlite-graph-memory[lite]>=0.3.6; extra == 'lite'
+Provides-Extra: test
+Requires-Dist: langchain-tests<2,>=1.0; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-sqlite-graph-memory
+
+A LangChain retriever over your own markdown notes, with the links between them. It runs
+[sqlite-graph-memory](https://github.com/tonydzi/sqlite-graph-memory): vector search finds
+the entry points, the `[[wikilinks]]` you already wrote are the graph, and a cross-encoder
+reranks what the 1-hop expansion pulled in. Everything runs on your machine: no server, no
+graph database, no LLM call at retrieval time.
+
+```bash
+pip install "langchain-sqlite-graph-memory[lite]"   # ONNX models, starts in seconds
+sgm-index /path/to/your/notes                      # builds ./index once
+```
+
+```python
+from langchain_sqlite_graph_memory import SQLiteGraphMemoryRetriever
+
+retriever = SQLiteGraphMemoryRetriever(index_dir="./index", k=8)
+
+for doc in retriever.invoke("why did we drop the graph database?"):
+    print(doc.metadata["rank"], doc.metadata["title"], doc.metadata["via_graph"])
+```
+
+Each result is a `Document`. `page_content` holds the matched chunk of the note. `metadata`
+holds `path`, `title`, `date`, `score` (cross-encoder), `rank`, and `via_graph`. `via_graph`
+is `True` when the note came in only through a wikilink from a top vector hit, so you can
+tell associative recall from direct recall.
+
+## Options
+
+| Argument | Default | What it does |
+|---|---|---|
+| `index_dir` | `$BRAIN_INDEX_DIR`, else `./index` | Folder with the `sgm-index` output |
+| `k` | 12 | Documents returned. `retriever.invoke(q, k=3)` overrides it per call |
+| `graph` | `"auto"` | `True` always follows wikilinks, `False` never does. `"auto"` follows them except for name or tool lookups, where the hop measured as noise |
+| `fetch_k` | 60 | Unique notes taken from vector search before expansion and rerank |
+| `encoder`, `reranker` | SGM models | Pass your own preloaded models, or fakes in tests |
+
+## In an agent
+
+```python
+from langchain_core.tools import create_retriever_tool
+
+recall = create_retriever_tool(
+    retriever, "recall_notes",
+    "Search my notes and the notes they link to. Use for anything I wrote down before.",
+)
+```
+
+## Scope, stated plainly
+
+- **This adapter calls the core library and adds nothing to retrieval.** It calls the same
+  functions `sgm-ask` calls (`query_sims`, `retrieve_candidates`, `expand_1hop`,
+  `rerank_candidates`). A test pins this: the adapter's order must equal a direct call of
+  those functions. On a real vault of 29,474 notes (105,383 chunks), the adapter returned the same 12 notes in the
+  same order as `sgm-ask --graph`.
+- **The index is two files on disk**, an embedding matrix (`.npy`) and note metadata
+  (`.pkl`), written by `sgm-index`. Wikilinks are read from the notes at query time.
+  SQLite stores the core library's session memory and A/B logs. The retriever needs only
+  the two index files.
+- Embeddings: `intfloat/multilingual-e5-base`. Reranker:
+  `cross-encoder/mmarco-mMiniLMv2-L12-H384-v1`. Both work for many languages.
+- Not implemented yet: a `VectorStore` (adding documents through LangChain) and a LangGraph
+  long-term memory store. Indexing goes through `sgm-index`.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+The suite includes LangChain's standard retriever tests (`langchain-tests`). It runs with
+fake models on a four-note vault: no download, no GPU, a few seconds.
+
+## License
+
+MIT

langchain_sqlite_graph_memory-0.1.0/README.md

@@ -0,0 +1,77 @@
+# langchain-sqlite-graph-memory
+
+A LangChain retriever over your own markdown notes, with the links between them. It runs
+[sqlite-graph-memory](https://github.com/tonydzi/sqlite-graph-memory): vector search finds
+the entry points, the `[[wikilinks]]` you already wrote are the graph, and a cross-encoder
+reranks what the 1-hop expansion pulled in. Everything runs on your machine: no server, no
+graph database, no LLM call at retrieval time.
+
+```bash
+pip install "langchain-sqlite-graph-memory[lite]"   # ONNX models, starts in seconds
+sgm-index /path/to/your/notes                      # builds ./index once
+```
+
+```python
+from langchain_sqlite_graph_memory import SQLiteGraphMemoryRetriever
+
+retriever = SQLiteGraphMemoryRetriever(index_dir="./index", k=8)
+
+for doc in retriever.invoke("why did we drop the graph database?"):
+    print(doc.metadata["rank"], doc.metadata["title"], doc.metadata["via_graph"])
+```
+
+Each result is a `Document`. `page_content` holds the matched chunk of the note. `metadata`
+holds `path`, `title`, `date`, `score` (cross-encoder), `rank`, and `via_graph`. `via_graph`
+is `True` when the note came in only through a wikilink from a top vector hit, so you can
+tell associative recall from direct recall.
+
+## Options
+
+| Argument | Default | What it does |
+|---|---|---|
+| `index_dir` | `$BRAIN_INDEX_DIR`, else `./index` | Folder with the `sgm-index` output |
+| `k` | 12 | Documents returned. `retriever.invoke(q, k=3)` overrides it per call |
+| `graph` | `"auto"` | `True` always follows wikilinks, `False` never does. `"auto"` follows them except for name or tool lookups, where the hop measured as noise |
+| `fetch_k` | 60 | Unique notes taken from vector search before expansion and rerank |
+| `encoder`, `reranker` | SGM models | Pass your own preloaded models, or fakes in tests |
+
+## In an agent
+
+```python
+from langchain_core.tools import create_retriever_tool
+
+recall = create_retriever_tool(
+    retriever, "recall_notes",
+    "Search my notes and the notes they link to. Use for anything I wrote down before.",
+)
+```
+
+## Scope, stated plainly
+
+- **This adapter calls the core library and adds nothing to retrieval.** It calls the same
+  functions `sgm-ask` calls (`query_sims`, `retrieve_candidates`, `expand_1hop`,
+  `rerank_candidates`). A test pins this: the adapter's order must equal a direct call of
+  those functions. On a real vault of 29,474 notes (105,383 chunks), the adapter returned the same 12 notes in the
+  same order as `sgm-ask --graph`.
+- **The index is two files on disk**, an embedding matrix (`.npy`) and note metadata
+  (`.pkl`), written by `sgm-index`. Wikilinks are read from the notes at query time.
+  SQLite stores the core library's session memory and A/B logs. The retriever needs only
+  the two index files.
+- Embeddings: `intfloat/multilingual-e5-base`. Reranker:
+  `cross-encoder/mmarco-mMiniLMv2-L12-H384-v1`. Both work for many languages.
+- Not implemented yet: a `VectorStore` (adding documents through LangChain) and a LangGraph
+  long-term memory store. Indexing goes through `sgm-index`.
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+The suite includes LangChain's standard retriever tests (`langchain-tests`). It runs with
+fake models on a four-note vault: no download, no GPU, a few seconds.
+
+## License
+
+MIT

langchain_sqlite_graph_memory-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-sqlite-graph-memory"
+version = "0.1.0"
+description = "LangChain retriever for sqlite-graph-memory: vector search + [[wikilink]] graph hop + cross-encoder rerank over your markdown notes. No server."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Anton Dziatkovskii" }]
+keywords = ["langchain", "retriever", "graph-rag", "obsidian", "wikilinks", "agent-memory", "rag"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "langchain-core>=1.0,<2",
+  "sqlite-graph-memory>=0.3.6",
+]
+
+[project.optional-dependencies]
+# The two local models. `lite` = ONNX, starts in seconds; `embeddings` = torch.
+lite = ["sqlite-graph-memory[lite]>=0.3.6"]
+embeddings = ["sqlite-graph-memory[embeddings]>=0.3.6"]
+test = ["pytest>=8", "langchain-tests>=1.0,<2"]
+
+[project.urls]
+Homepage = "https://github.com/tonydzi/langchain-sqlite-graph-memory"
+Repository = "https://github.com/tonydzi/langchain-sqlite-graph-memory"
+Issues = "https://github.com/tonydzi/langchain-sqlite-graph-memory/issues"
+"Core library" = "https://github.com/tonydzi/sqlite-graph-memory"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_sqlite_graph_memory"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

langchain_sqlite_graph_memory-0.1.0/src/langchain_sqlite_graph_memory/__init__.py

@@ -0,0 +1,5 @@
+"""LangChain integration for sqlite-graph-memory (Graph RAG over markdown notes)."""
+from langchain_sqlite_graph_memory.retrievers import SQLiteGraphMemoryRetriever
+
+__all__ = ["SQLiteGraphMemoryRetriever"]
+__version__ = "0.1.0"

langchain_sqlite_graph_memory-0.1.0/src/langchain_sqlite_graph_memory/retrievers.py

@@ -0,0 +1,146 @@
+"""LangChain retriever over a sqlite-graph-memory index.
+
+Паспорт (for the people who maintain this):
+  in:  a query string; an index built by `sgm-index` (two files: _brain_e5.npy,
+       _brain_e5_meta.pkl) in `index_dir`.
+  out: list[Document], best first. page_content = the matched chunk; metadata =
+       path, title, date, score, rank, via_graph.
+  who calls: any LangChain / LangGraph app (`retriever.invoke(q)`, a tool, a chain).
+  what breaks it: sqlite-graph-memory changing the signatures of load_index,
+       query_sims, retrieve_candidates, expand_1hop, rerank_candidates. The test
+       suite pins that contract with fake models, so a drift fails CI, not a user.
+  рельса: none, no LLM call. Embedding + cross-encoder run locally.
+
+It runs the SAME pipeline functions `sgm-ask` runs (imported from
+sqlite_graph_memory.brain_ask), so recall through LangChain cannot drift away from
+recall through the CLI or the MCP server.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, List, Literal, Optional, Union
+
+from langchain_core.callbacks import CallbackManagerForRetrieverRun
+from langchain_core.documents import Document
+from langchain_core.retrievers import BaseRetriever
+from pydantic import ConfigDict, Field, PrivateAttr
+
+from sqlite_graph_memory import brain_ask as _sgm
+
+GraphMode = Union[bool, Literal["auto"]]
+
+
+class SQLiteGraphMemoryRetriever(BaseRetriever):
+    """Associative recall over a folder of markdown notes.
+
+    Vector search finds entry points, 1-hop ``[[wikilinks]]`` pull in linked notes,
+    a cross-encoder reranks the union. The index is two files on disk; no server.
+
+    Setup:
+        .. code-block:: bash
+
+            pip install "langchain-sqlite-graph-memory[lite]"
+            sgm-index /path/to/vault --out ./index
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_sqlite_graph_memory import SQLiteGraphMemoryRetriever
+
+            retriever = SQLiteGraphMemoryRetriever(index_dir="./index", k=8)
+
+    Invoke:
+        .. code-block:: python
+
+            docs = retriever.invoke("why did we drop the graph database?")
+            for d in docs:
+                print(d.metadata["rank"], d.metadata["title"], d.metadata["via_graph"])
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    index_dir: Optional[str] = None
+    """Directory with the `sgm-index` output. Default: env BRAIN_INDEX_DIR, then ./index."""
+    k: int = Field(default=_sgm.TOPN, ge=1)
+    """How many documents to return."""
+    graph: GraphMode = "auto"
+    """Wikilink expansion. True = always, False = never (plain vector + rerank),
+    "auto" = on, except for name/tool lookups, where it measured as noise
+    (sqlite_graph_memory.brain_ask.looks_like_entity)."""
+    fetch_k: int = Field(default=_sgm.TOPK_RETRIEVE, ge=1)
+    """Unique notes taken from vector search before expansion and rerank."""
+    encoder: Any = None
+    """Optional preloaded encoder with `.encode(...)`. Default: the SGM e5 model."""
+    reranker: Any = None
+    """Optional preloaded cross-encoder with `.predict(pairs)`. Default: the SGM reranker."""
+
+    _emb: Any = PrivateAttr(default=None)
+    _meta: Any = PrivateAttr(default=None)
+    _by_base: Any = PrivateAttr(default=None)
+
+    # ------------------------------------------------------------------ loading
+    def _index_paths(self) -> tuple[Path, Path]:
+        base = Path(self.index_dir or os.getenv("BRAIN_INDEX_DIR", "index"))
+        return base / "_brain_e5.npy", base / "_brain_e5_meta.pkl"
+
+    def _ensure_loaded(self) -> None:
+        if self._meta is not None:
+            return
+        emb_path, meta_path = self._index_paths()
+        if not emb_path.exists() or not meta_path.exists():
+            raise FileNotFoundError(
+                "No sqlite-graph-memory index at %s. Build one first: "
+                "sgm-index <notes folder> (see https://github.com/tonydzi/sqlite-graph-memory)"
+                % emb_path.parent
+            )
+        self._emb, self._meta = _sgm.load_index(emb_path, meta_path)
+        self._by_base = _sgm.index_by_basename(self._meta)
+        if self.encoder is None:
+            self.encoder = _sgm.load_encoder()
+        if self.reranker is None:
+            self.reranker = _sgm.load_reranker()
+
+    def _use_graph(self, query: str) -> bool:
+        if self.graph == "auto":
+            return not _sgm.looks_like_entity(query)
+        return bool(self.graph)
+
+    # ------------------------------------------------------------------ retrieval
+    def _get_relevant_documents(
+        self,
+        query: str,
+        *,
+        run_manager: CallbackManagerForRetrieverRun,
+        **kwargs: Any,
+    ) -> List[Document]:
+        k = int(kwargs.get("k", self.k))
+        self._ensure_loaded()
+        meta = self._meta
+        sims = _sgm.query_sims(self.encoder, self._emb, query)
+        base_order = _sgm.retrieve_candidates(sims, meta, topk=self.fetch_k)
+        added: List[int] = []
+        if base_order and self._use_graph(query):
+            added = _sgm.expand_1hop(sims, meta, base_order, by_base=self._by_base)
+        via_graph = set(added)
+        ranked = _sgm.rerank_candidates(
+            self.reranker, query, base_order + added, meta, topn=k
+        )
+        docs = []
+        for rank, (i, score) in enumerate(ranked, 1):
+            m = meta[i]
+            docs.append(
+                Document(
+                    page_content=m.get("snippet", ""),
+                    metadata={
+                        "path": m.get("path"),
+                        "title": m.get("title"),
+                        "date": m.get("date"),
+                        "score": float(score),
+                        "rank": rank,
+                        "via_graph": i in via_graph,
+                        "source": m.get("path"),
+                    },
+                )
+            )
+        return docs

langchain_sqlite_graph_memory-0.1.0/tests/fakes.py

@@ -0,0 +1,65 @@
+"""Tiny stand-ins for the two local models, so the suite runs in seconds with no torch,
+no ONNX and no network. They implement exactly the methods the SGM pipeline calls."""
+from __future__ import annotations
+
+import hashlib
+import pickle
+import re
+from pathlib import Path
+
+import numpy as np
+
+DIM = 64
+_WORD = re.compile(r"[a-z]+")
+
+
+def _words(text: str) -> list[str]:
+    return [w for w in _WORD.findall(text.lower()) if w not in {"query", "passage"}]
+
+
+def _vec(text: str) -> np.ndarray:
+    v = np.zeros(DIM, dtype="float32")
+    for w in _words(text):
+        v[int(hashlib.md5(w.encode()).hexdigest(), 16) % DIM] += 1.0
+    n = np.linalg.norm(v)
+    return v / n if n else v
+
+
+class FakeEncoder:
+    def encode(self, texts, normalize_embeddings=True, convert_to_numpy=True):
+        return np.stack([_vec(t) for t in texts])
+
+
+class FakeReranker:
+    """Score = shared words between query and chunk, plus a small floor so that a linked
+    note with no shared words still ranks (below every note that shares a word)."""
+
+    def predict(self, pairs):
+        out = []
+        for q, doc in pairs:
+            out.append(len(set(_words(q)) & set(_words(doc))) + 0.01)
+        return np.array(out, dtype="float32")
+
+
+NOTES = {
+    "alpha": "Deploy pipeline and release checklist. Before shipping see [[beta]].",
+    "beta": "Rollback plan for outages and incidents.",
+    "gamma": "Cooking recipes: pasta, sauce, basil.",
+    "delta": "Release notes template for the deploy of a new version.",
+}
+
+
+def build_vault_and_index(root: Path) -> Path:
+    """Write NOTES as .md files under root/vault and an SGM-format index under root/index."""
+    vault, index = root / "vault", root / "index"
+    vault.mkdir(parents=True, exist_ok=True)
+    index.mkdir(parents=True, exist_ok=True)
+    meta, rows = [], []
+    for stem, body in NOTES.items():
+        p = vault / ("%s.md" % stem)
+        p.write_text(body, encoding="utf-8")
+        meta.append({"path": str(p), "title": stem, "snippet": body, "date": "2026-11-05"})
+        rows.append(_vec("passage: " + body))
+    np.save(index / "_brain_e5.npy", np.stack(rows))
+    (index / "_brain_e5_meta.pkl").write_bytes(pickle.dumps(meta))
+    return index

langchain_sqlite_graph_memory-0.1.0/tests/integration_tests/test_standard.py

@@ -0,0 +1,27 @@
+"""LangChain's own standard test suite for retrievers (langchain-tests), run against a
+tiny on-disk index with fake models, so it needs no network and no GPU."""
+import tempfile
+from functools import cached_property
+from pathlib import Path
+
+from langchain_tests.integration_tests import RetrieversIntegrationTests
+
+from langchain_sqlite_graph_memory import SQLiteGraphMemoryRetriever
+from tests.fakes import FakeEncoder, FakeReranker, build_vault_and_index
+
+_TMP = Path(tempfile.mkdtemp(prefix="lc-sgm-"))
+_INDEX = str(build_vault_and_index(_TMP))
+
+
+class TestSQLiteGraphMemoryRetrieverStandard(RetrieversIntegrationTests):
+    @property
+    def retriever_constructor(self) -> type[SQLiteGraphMemoryRetriever]:
+        return SQLiteGraphMemoryRetriever
+
+    @property
+    def retriever_constructor_params(self) -> dict:
+        return {"index_dir": _INDEX, "encoder": FakeEncoder(), "reranker": FakeReranker()}
+
+    @property
+    def retriever_query_example(self) -> str:
+        return "deploy release checklist"

langchain_sqlite_graph_memory-0.1.0/tests/unit_tests/test_retriever.py

@@ -0,0 +1,89 @@
+import pytest
+from langchain_core.documents import Document
+
+from langchain_sqlite_graph_memory import SQLiteGraphMemoryRetriever
+from tests.fakes import FakeEncoder, FakeReranker, build_vault_and_index
+
+
+@pytest.fixture()
+def index_dir(tmp_path):
+    return str(build_vault_and_index(tmp_path))
+
+
+def make(index_dir, **kw):
+    return SQLiteGraphMemoryRetriever(
+        index_dir=index_dir, encoder=FakeEncoder(), reranker=FakeReranker(), **kw
+    )
+
+
+def test_returns_documents_with_metadata(index_dir):
+    docs = make(index_dir, k=2).invoke("deploy release checklist")
+    assert docs and all(isinstance(d, Document) for d in docs)
+    top = docs[0]
+    assert top.metadata["title"] == "alpha"
+    assert top.metadata["rank"] == 1
+    assert top.metadata["path"].endswith("alpha.md")
+    assert top.metadata["source"] == top.metadata["path"]
+    assert "release checklist" in top.page_content
+
+
+def test_wikilink_hop_brings_in_linked_note(index_dir):
+    # fetch_k=1: vector search alone sees only `alpha`; `beta` shares no word with the
+    # query and is reachable only through alpha's [[beta]] link.
+    docs = make(index_dir, k=3, fetch_k=1, graph=True).invoke("deploy checklist")
+    titles = [d.metadata["title"] for d in docs]
+    assert titles == ["alpha", "beta"]
+    assert docs[1].metadata["via_graph"] is True
+    assert docs[0].metadata["via_graph"] is False
+
+
+def test_graph_off_is_plain_vector_plus_rerank(index_dir):
+    docs = make(index_dir, k=3, fetch_k=1, graph=False).invoke("deploy checklist")
+    assert [d.metadata["title"] for d in docs] == ["alpha"]
+
+
+def test_auto_skips_graph_for_entity_lookups(index_dir):
+    # "Obsidian" is a known tool token -> looks_like_entity -> no expansion
+    docs = make(index_dir, k=3, fetch_k=1).invoke("Obsidian")
+    assert not any(d.metadata["via_graph"] for d in docs)
+    docs = make(index_dir, k=3, fetch_k=1).invoke("deploy checklist")
+    assert any(d.metadata["via_graph"] for d in docs)
+
+
+def test_k_kwarg_overrides_constructor(index_dir):
+    r = make(index_dir, k=4)
+    assert len(r.invoke("release deploy")) == 4
+    assert len(r.invoke("release deploy", k=1)) == 1
+
+
+def test_missing_index_says_how_to_build_one(tmp_path):
+    r = make(str(tmp_path / "nowhere"))
+    with pytest.raises(FileNotFoundError, match="sgm-index"):
+        r.invoke("anything")
+
+
+def test_same_order_as_the_sgm_pipeline(index_dir):
+    """The adapter must not re-implement retrieval: its order equals what the SGM
+    functions produce when called directly, the way sgm-ask calls them."""
+    from sqlite_graph_memory import brain_ask as sgm
+    from pathlib import Path
+
+    q = "release deploy version"
+    emb, meta = sgm.load_index(Path(index_dir) / "_brain_e5.npy", Path(index_dir) / "_brain_e5_meta.pkl")
+    sims = sgm.query_sims(FakeEncoder(), emb, q)
+    base = sgm.retrieve_candidates(sims, meta)
+    added = sgm.expand_1hop(sims, meta, base)
+    want = [meta[i]["title"] for i, _ in sgm.rerank_candidates(FakeReranker(), q, base + added, meta, topn=3)]
+    got = [d.metadata["title"] for d in make(index_dir, k=3, graph=True).invoke(q)]
+    assert got == want
+
+
+async def _ainvoke(r, q):
+    return await r.ainvoke(q)
+
+
+def test_async_invoke(index_dir):
+    import asyncio
+
+    docs = asyncio.run(_ainvoke(make(index_dir, k=2), "deploy release"))
+    assert len(docs) == 2