langchain-sqlite-graph-memory 0.1.0__py3-none-any.whl

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,7 @@
+langchain_sqlite_graph_memory/__init__.py,sha256=JW0teu2TVrBaK63pXEOh1AeDukNdvnVOwkgwuop5mFY,229
+langchain_sqlite_graph_memory/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langchain_sqlite_graph_memory/retrievers.py,sha256=rb7tAbxoJ4xwzPmlMZFctkD82v5kxrLRh6kUNNwohw8,5932
+langchain_sqlite_graph_memory-0.1.0.dist-info/METADATA,sha256=f2W8XyaJZryVUUkHwgeQdgiB1hiB7GEQSPGFoDrOx-c,6089
+langchain_sqlite_graph_memory-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+langchain_sqlite_graph_memory-0.1.0.dist-info/licenses/LICENSE,sha256=p88nZdrfMUiES3_MpUEwhGmqz2hQFpyMh0k0cqdpfU8,1082
+langchain_sqlite_graph_memory-0.1.0.dist-info/RECORD,,

langchain_sqlite_graph_memory-0.1.0.dist-info/WHEEL

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

langchain_sqlite_graph_memory-0.1.0.dist-info/licenses/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.