langgraph-velesdb 4.2.0__tar.gz

langgraph_velesdb-4.2.0/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2024-2026 Wiscale France
+
+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.
+
+---
+
+Note: This MIT license applies to the LangChain integration code only.
+VelesDB Core itself is licensed under the Elastic License 2.0 (ELv2).
+See https://github.com/cyberlife-coder/VelesDB for VelesDB Core licensing.

langgraph_velesdb-4.2.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: langgraph-velesdb
+Version: 4.2.0
+Summary: LangGraph memory tools for VelesDB: drop the why() knowledge-graph memory wedge into any LangGraph agent.
+Author-email: VelesDB Team <contact@wiscale.fr>
+License: MIT
+Project-URL: Homepage, https://velesdb.com
+Project-URL: Repository, https://github.com/cyberlife-coder/VelesDB
+Keywords: langgraph,langchain,velesdb,agent-memory,knowledge-graph,local-first,why,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langchain-core<2.0.0,>=0.3.0
+Requires-Dist: velesdb>=3.12.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=7.0; extra == "dev"
+Requires-Dist: langgraph>=0.2.0; extra == "dev"
+Dynamic: license-file
+
+# langgraph-velesdb
+
+Drop VelesDB's local-first agent memory — the **`why()` knowledge-graph wedge** —
+into any [LangGraph](https://github.com/langchain-ai/langgraph) agent in three lines.
+
+Most agent memory is vector recall: it finds text that *looks like* the query.
+VelesDB **connects** memories with typed links, so `why()` answers with the
+best-matching memory **plus the connected subgraph** — context that shares no
+words with the question, which a plain vector recall is blind to. The store is on
+disk, so memory persists across agent runs.
+
+![recall() finds the booking but misses the reason; why() reaches it through typed links, across a session restart](https://raw.githubusercontent.com/cyberlife-coder/VelesDB/develop/examples/agent_memory/why_across_sessions.gif)
+
+## Install
+
+```bash
+pip install langgraph-velesdb        # pulls langchain-core + velesdb
+```
+
+## Use
+
+```python
+from langgraph.prebuilt import create_react_agent
+from langgraph_velesdb import make_memory_tools
+
+# Offline by default (hash embedder); pass a configured MemoryService for Ollama.
+agent = create_react_agent(llm, make_memory_tools("./agent_memory"))
+```
+
+`make_memory_tools` returns ten tools the agent can call:
+
+| Tool                   | What it does |
+|------------------------|--------------|
+| `remember`             | store a fact (optionally with `links`, `metadata`, `ttl_seconds`), return its id |
+| `recall`               | semantic (vector) recall — no metadata |
+| `recall_where`         | filtered recall (metadata `[field, op, value]` triples) **with metadata attached**, e.g. the auto `_veles_date` stamp |
+| `recall_fused`         | fused vector + graph recall; pass `date_field="_veles_date"` for a dated timeline |
+| `relate`               | link two memories with a typed edge |
+| `forget`               | delete a memory by id (`True` if it existed, `False` if it was already gone) |
+| `feedback`             | reinforce or weaken a memory after using it, closing the self-improving recall loop |
+| `why`                  | best-matching memory **+ its connected subgraph** (the wedge) |
+| `save_working_context` | persist the current goal/constraints/decisions/pending actions under a project + session |
+| `load_working_context` | resume a prior run's working context — call at the start of a session |
+
+For a pre-configured backend (e.g. Ollama embeddings), build the service yourself
+and pass it through:
+
+```python
+from velesdb import MemoryService
+tools = make_memory_tools(service=MemoryService("./agent_memory"))
+```
+
+### Cross-run resumption
+
+`save_working_context` / `load_working_context` let an agent pick up a task
+across separate runs instead of restarting from scratch:
+
+`make_memory_tools` returns a *list* of tools, so index them by name first
+(the same pattern LangGraph's `ToolNode`/`create_react_agent` use internally):
+
+```python
+tools = {t.name: t for t in make_memory_tools("./agent_memory")}
+
+tools["save_working_context"].invoke({
+    "project": "veles",
+    "session": "issue-1546",
+    "working": {
+        "goal": "ship the langgraph tool set",
+        "pending_actions": ["open the PR"],
+    },
+})
+
+# ... next run, same project + session:
+tools["load_working_context"].invoke({"project": "veles", "session": "issue-1546"})
+```
+
+### Dated recall
+
+Every `remember`-ed fact is auto-stamped with `_veles_date` (today, as a
+`YYYYMMDD` int) unless you set that metadata key yourself. Point
+`recall_fused` at it to get a chronological timeline instead of a ranked list:
+
+```python
+tools = {t.name: t for t in make_memory_tools("./agent_memory")}
+
+tools["recall_fused"].invoke({"query": "what changed this week", "date_field": "_veles_date"})
+# -> {"memories": [...], "dated_context": "...", "now": "..."}
+```
+
+## Compatibility
+
+This package requires `velesdb>=3.12.0`, the highest version published to
+PyPI at the time of writing. `feedback`, `save_working_context`,
+`load_working_context`, and the automatic `_veles_date` metadata stamp landed
+in `velesdb`/`velesdb-memory` *after* the 3.12.0 release cut and are not yet
+in a published wheel. On a plain 3.12.0 install those three tools detect the
+missing binding method at call time and return an error payload instead of
+raising, e.g.:
+
+```json
+{"error": "feedback requires velesdb > 3.12.0 — upgrade with `pip install -U velesdb`"}
+```
+
+so a single unsupported call surfaces to the agent as a normal tool result it
+can react to, instead of an uncaught `AttributeError` killing the whole graph
+run. `recall_where`/`recall_fused` still work, but their `metadata` stays
+empty for auto-dating until you upgrade. `forget` works on 3.12.0 too, but
+returns `None` instead of a `True`/`False` existed-or-not signal. The floor
+will be bumped again once a `velesdb` release past 3.12.0 ships.
+
+`list_working_contexts` (browse saved sessions for a project) is not exposed
+here: it exists on the WASM and MCP surfaces but not yet on the `velesdb`
+Python binding (`MemoryService`), and this package only ever calls the
+binding — no memory logic is reimplemented in this MIT-licensed integration.
+It will be added once the Python binding grows the method.
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Wraps [`velesdb`](https://pypi.org/project/velesdb/),
+which is under the VelesDB Core License 1.0.

langgraph_velesdb-4.2.0/README.md

@@ -0,0 +1,120 @@
+# langgraph-velesdb
+
+Drop VelesDB's local-first agent memory — the **`why()` knowledge-graph wedge** —
+into any [LangGraph](https://github.com/langchain-ai/langgraph) agent in three lines.
+
+Most agent memory is vector recall: it finds text that *looks like* the query.
+VelesDB **connects** memories with typed links, so `why()` answers with the
+best-matching memory **plus the connected subgraph** — context that shares no
+words with the question, which a plain vector recall is blind to. The store is on
+disk, so memory persists across agent runs.
+
+![recall() finds the booking but misses the reason; why() reaches it through typed links, across a session restart](https://raw.githubusercontent.com/cyberlife-coder/VelesDB/develop/examples/agent_memory/why_across_sessions.gif)
+
+## Install
+
+```bash
+pip install langgraph-velesdb        # pulls langchain-core + velesdb
+```
+
+## Use
+
+```python
+from langgraph.prebuilt import create_react_agent
+from langgraph_velesdb import make_memory_tools
+
+# Offline by default (hash embedder); pass a configured MemoryService for Ollama.
+agent = create_react_agent(llm, make_memory_tools("./agent_memory"))
+```
+
+`make_memory_tools` returns ten tools the agent can call:
+
+| Tool                   | What it does |
+|------------------------|--------------|
+| `remember`             | store a fact (optionally with `links`, `metadata`, `ttl_seconds`), return its id |
+| `recall`               | semantic (vector) recall — no metadata |
+| `recall_where`         | filtered recall (metadata `[field, op, value]` triples) **with metadata attached**, e.g. the auto `_veles_date` stamp |
+| `recall_fused`         | fused vector + graph recall; pass `date_field="_veles_date"` for a dated timeline |
+| `relate`               | link two memories with a typed edge |
+| `forget`               | delete a memory by id (`True` if it existed, `False` if it was already gone) |
+| `feedback`             | reinforce or weaken a memory after using it, closing the self-improving recall loop |
+| `why`                  | best-matching memory **+ its connected subgraph** (the wedge) |
+| `save_working_context` | persist the current goal/constraints/decisions/pending actions under a project + session |
+| `load_working_context` | resume a prior run's working context — call at the start of a session |
+
+For a pre-configured backend (e.g. Ollama embeddings), build the service yourself
+and pass it through:
+
+```python
+from velesdb import MemoryService
+tools = make_memory_tools(service=MemoryService("./agent_memory"))
+```
+
+### Cross-run resumption
+
+`save_working_context` / `load_working_context` let an agent pick up a task
+across separate runs instead of restarting from scratch:
+
+`make_memory_tools` returns a *list* of tools, so index them by name first
+(the same pattern LangGraph's `ToolNode`/`create_react_agent` use internally):
+
+```python
+tools = {t.name: t for t in make_memory_tools("./agent_memory")}
+
+tools["save_working_context"].invoke({
+    "project": "veles",
+    "session": "issue-1546",
+    "working": {
+        "goal": "ship the langgraph tool set",
+        "pending_actions": ["open the PR"],
+    },
+})
+
+# ... next run, same project + session:
+tools["load_working_context"].invoke({"project": "veles", "session": "issue-1546"})
+```
+
+### Dated recall
+
+Every `remember`-ed fact is auto-stamped with `_veles_date` (today, as a
+`YYYYMMDD` int) unless you set that metadata key yourself. Point
+`recall_fused` at it to get a chronological timeline instead of a ranked list:
+
+```python
+tools = {t.name: t for t in make_memory_tools("./agent_memory")}
+
+tools["recall_fused"].invoke({"query": "what changed this week", "date_field": "_veles_date"})
+# -> {"memories": [...], "dated_context": "...", "now": "..."}
+```
+
+## Compatibility
+
+This package requires `velesdb>=3.12.0`, the highest version published to
+PyPI at the time of writing. `feedback`, `save_working_context`,
+`load_working_context`, and the automatic `_veles_date` metadata stamp landed
+in `velesdb`/`velesdb-memory` *after* the 3.12.0 release cut and are not yet
+in a published wheel. On a plain 3.12.0 install those three tools detect the
+missing binding method at call time and return an error payload instead of
+raising, e.g.:
+
+```json
+{"error": "feedback requires velesdb > 3.12.0 — upgrade with `pip install -U velesdb`"}
+```
+
+so a single unsupported call surfaces to the agent as a normal tool result it
+can react to, instead of an uncaught `AttributeError` killing the whole graph
+run. `recall_where`/`recall_fused` still work, but their `metadata` stays
+empty for auto-dating until you upgrade. `forget` works on 3.12.0 too, but
+returns `None` instead of a `True`/`False` existed-or-not signal. The floor
+will be bumped again once a `velesdb` release past 3.12.0 ships.
+
+`list_working_contexts` (browse saved sessions for a project) is not exposed
+here: it exists on the WASM and MCP surfaces but not yet on the `velesdb`
+Python binding (`MemoryService`), and this package only ever calls the
+binding — no memory logic is reimplemented in this MIT-licensed integration.
+It will be added once the Python binding grows the method.
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Wraps [`velesdb`](https://pypi.org/project/velesdb/),
+which is under the VelesDB Core License 1.0.

langgraph_velesdb-4.2.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "langgraph-velesdb"
+version = "4.2.0"
+description = "LangGraph memory tools for VelesDB: drop the why() knowledge-graph memory wedge into any LangGraph agent."
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "VelesDB Team", email = "contact@wiscale.fr"}
+]
+keywords = ["langgraph", "langchain", "velesdb", "agent-memory", "knowledge-graph", "local-first", "why", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "langchain-core>=0.3.0,<2.0.0",
+    # 3.12.0 is the highest velesdb release published to PyPI as of this
+    # writing. It ships forget/recall_where/recall_fused, but not yet
+    # MemoryService.feedback/save_working_context/load_working_context, nor
+    # the automatic `_veles_date` metadata stamp (velesdb-memory 0.11.0) —
+    # those tools will raise AttributeError, and recall_where/recall_fused's
+    # `metadata` stays empty for auto-dating, until velesdb publishes past
+    # 3.12.0. See README.md's "Compatibility" section.
+    "velesdb>=3.12.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0,<9.0",
+    "langgraph>=0.2.0",
+]
+
+[project.urls]
+Homepage = "https://velesdb.com"
+Repository = "https://github.com/cyberlife-coder/VelesDB"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+langgraph_velesdb = ["py.typed"]

langgraph_velesdb-4.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

langgraph_velesdb-4.2.0/src/langgraph_velesdb/__init__.py

@@ -0,0 +1,21 @@
+"""LangGraph memory tools for VelesDB — the ``why()`` knowledge-graph wedge.
+
+Drop VelesDB's local-first agent memory into any LangGraph agent:
+
+    >>> from langgraph.prebuilt import create_react_agent
+    >>> from langgraph_velesdb import make_memory_tools
+    >>>
+    >>> agent = create_react_agent(llm, make_memory_tools("./agent_memory"))
+
+``make_memory_tools`` returns the full VelesDB memory tool set: ``remember``,
+``recall``, ``recall_where``, ``recall_fused``, ``relate``, ``forget``,
+``feedback``, and the differentiator ``why`` — which answers with the
+best-matching memory *plus* the connected subgraph a vector recall is blind
+to — plus ``save_working_context``/``load_working_context`` for cross-run
+resumption. The store is on disk, so memory persists across agent runs.
+"""
+
+from langgraph_velesdb.tools import make_memory_tools
+
+__all__ = ["make_memory_tools"]
+__version__ = "4.2.0"

langgraph_velesdb-4.2.0/src/langgraph_velesdb/tools.py

@@ -0,0 +1,245 @@
+"""LangGraph / LangChain tools backed by VelesDB's high-level ``MemoryService``.
+
+A thin adapter: each tool is a small method on ``_MemoryToolkit``, bound to one
+``MemoryService`` (the core). No state or logic lives here beyond shaping
+inputs/outputs for the tool layer — the engine does the work. Methods live on
+a class (rather than as closures inside ``make_memory_tools``) so each tool's
+own cyclomatic complexity is what a linter measures, instead of all ten
+rolling up into one function.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from langchain_core.tools import BaseTool, StructuredTool  # nosemgrep: ai.python.detect-langchain.detect-langchain  # this package IS the LangChain connector
+
+try:
+    from velesdb import MemoryService
+except ImportError as exc:  # pragma: no cover - import guard
+    raise ImportError(
+        "velesdb is required for langgraph-velesdb. Install with: pip install velesdb"
+    ) from exc
+
+
+def make_memory_tools(
+    path: Optional[str] = None,
+    *,
+    service: Optional["MemoryService"] = None,
+) -> list[BaseTool]:
+    """Build the full VelesDB memory tool set for a LangGraph agent.
+
+    Returns ``remember`` / ``recall`` / ``recall_where`` / ``recall_fused`` /
+    ``relate`` / ``forget`` / ``feedback`` / ``why`` / ``save_working_context``
+    / ``load_working_context``.
+
+    Pass a ``path`` to open a local on-disk store (offline hash embedder), or a
+    pre-configured ``service`` (e.g. an Ollama-backed ``MemoryService``) to reuse
+    it. The store is on disk, so memory persists across agent runs.
+    """
+    toolkit = _MemoryToolkit(_resolve_service(path, service))
+    return [
+        StructuredTool.from_function(fn)
+        for fn in (
+            toolkit.remember,
+            toolkit.recall,
+            toolkit.recall_where,
+            toolkit.recall_fused,
+            toolkit.relate,
+            toolkit.forget,
+            toolkit.feedback,
+            toolkit.why,
+            toolkit.save_working_context,
+            toolkit.load_working_context,
+        )
+    ]
+
+
+class _MemoryToolkit:
+    """Binds one ``MemoryService`` to the ten tool methods ``make_memory_tools``
+    wraps into ``StructuredTool``\\ s. Not part of the public API."""
+
+    def __init__(self, mem: "MemoryService") -> None:
+        self._mem = mem
+
+    def remember(
+        self,
+        fact: str,
+        links: Optional[list[list[Any]]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        ttl_seconds: Optional[int] = None,
+    ) -> int:
+        """Store a fact in long-term memory and return its id.
+
+        ``links`` optionally wires typed outgoing edges to existing memory ids
+        at write time — each item is ``[target_id, relation]`` (equivalent to
+        calling ``relate`` right after). ``metadata`` attaches key/value pairs
+        ``recall_where``/``recall_fused`` can later filter on (every fact also
+        gets an automatic ``_veles_date`` stamp — today's date as a
+        ``YYYYMMDD`` int — unless you set that key yourself). ``ttl_seconds``
+        makes the fact expire, and stop being recalled, after that many
+        seconds. All three are optional; a bare ``remember(fact)`` behaves
+        exactly as before.
+        """
+        return self._mem.remember(
+            fact,
+            links=_as_tuples(links),
+            metadata=metadata,
+            ttl_seconds=ttl_seconds,
+        )
+
+    def recall(self, query: str, k: int = 5) -> list[dict[str, Any]]:
+        """Recall memories semantically similar to the query (vector search).
+
+        Each hit's ``metadata`` is always ``None`` on this path — use
+        ``recall_where`` (or ``recall_fused``) when you need each memory's
+        metadata, including the automatic ``_veles_date`` stamp.
+        """
+        return self._mem.recall(query, k)
+
+    def recall_where(
+        self,
+        query: str,
+        filters: Optional[list[list[Any]]] = None,
+        k: int = 5,
+    ) -> list[dict[str, Any]]:
+        """Recall memories similar to the query, filtered by metadata, with
+        each hit's metadata attached.
+
+        ``filters`` is a list of ``[field, op, value]`` triples, ``op`` one of
+        ``"eq"``/``"ne"``/``"lt"``/``"le"``/``"gt"``/``"ge"`` — e.g.
+        ``[["_veles_date", "ge", 20260101]]`` keeps only facts stamped on or
+        after that date. Pass an empty list (the default) for no filtering.
+        Unlike plain ``recall``, every hit's ``metadata`` dict is returned,
+        including the automatic ``_veles_date`` stamp every fact gets at
+        write time.
+        """
+        return self._mem.recall_where(query, _as_tuples(filters) or [], k)
+
+    def recall_fused(
+        self,
+        query: str,
+        k: int = 5,
+        metadata_filter: Optional[dict[str, Any]] = None,
+        date_field: Optional[str] = None,
+    ) -> Any:
+        """Fused vector + graph recall: walks the graph from the top hit and
+        folds in any connected fact a plain ``recall`` would miss.
+
+        ``metadata_filter`` is an optional exact-match metadata filter. Pass
+        ``date_field="_veles_date"`` (the automatic stamp every fact gets) to
+        get back a dict with a chronological, date-prefixed timeline
+        (``dated_context``) instead of a plain list — useful for "what
+        happened, in order" questions. Omit ``date_field`` for the plain-list
+        form.
+        """
+        return self._mem.recall_fused(query, k, metadata_filter, date_field=date_field)
+
+    def relate(self, from_id: int, to_id: int, relation: str) -> int:
+        """Link two memories with a typed edge (``from_id`` -> ``to_id``)."""
+        return self._mem.relate(from_id, to_id, relation)
+
+    def forget(self, memory_id: int) -> bool:
+        """Delete a memory by id.
+
+        Returns ``True`` if a memory actually existed under ``memory_id`` and
+        was removed, ``False`` if there was nothing stored there (a stale id
+        or a typo) — a no-op, not an error.
+        """
+        return self._mem.forget(memory_id)
+
+    def feedback(self, memory_id: int, success: bool) -> Any:
+        """Reinforce or weaken a memory after using it, and return its
+        updated confidence in ``[0.0, 1.0]``.
+
+        Call this once you know whether a memory you recalled actually helped
+        answer the question (``success=True``) or was misleading/irrelevant
+        (``success=False``). This closes the self-improving loop: future
+        ``recall``/``recall_where``/``recall_fused`` calls rank
+        higher-confidence memories higher.
+
+        If the installed ``velesdb`` predates this method, returns
+        ``{"error": "..."}`` instead of raising, telling you to upgrade.
+        """
+        if not hasattr(self._mem, "feedback"):
+            return _unsupported("feedback")
+        return self._mem.feedback(memory_id, success)
+
+    def why(self, question: str, max_hops: int = 2) -> dict[str, Any]:
+        """Explain something: the best-matching memory plus the connected
+        subgraph reachable through typed links — context a plain recall misses."""
+        return self._mem.why(question, max_hops)
+
+    def save_working_context(
+        self,
+        project: str,
+        session: str,
+        working: dict[str, Any],
+    ) -> Any:
+        """Persist the current working state under ``project`` + ``session``
+        so a later run can resume exactly where this one left off.
+
+        ``working`` is free-form but conventionally shaped like
+        ``{"goal": str, "active_constraints": [...], "verified_facts": [...],
+        "open_hypotheses": [...], "decisions": [...], "exact_evidence": [...],
+        "pending_actions": [...]}`` — call this near the end of a session, or
+        whenever the plan materially changes. Saving again under the same
+        ``project`` + ``session`` replaces the previous state (not a merge).
+
+        If the installed ``velesdb`` predates this method, returns
+        ``{"error": "..."}`` instead of raising, telling you to upgrade.
+        """
+        if not hasattr(self._mem, "save_working_context"):
+            return _unsupported("save_working_context")
+        return self._mem.save_working_context(project, session, working)
+
+    def load_working_context(self, project: str, session: str) -> Any:
+        """Load the working context previously saved under ``project`` +
+        ``session`` by ``save_working_context``.
+
+        Call this at the very start of a new run, before doing anything else,
+        to resume a prior session instead of restarting from scratch. Returns
+        ``None`` when nothing was ever saved under that exact
+        ``project``/``session`` pair — not an error, just a fresh start.
+
+        If the installed ``velesdb`` predates this method, returns
+        ``{"error": "..."}`` instead of raising, telling you to upgrade.
+        """
+        if not hasattr(self._mem, "load_working_context"):
+            return _unsupported("load_working_context")
+        return self._mem.load_working_context(project, session)
+
+
+def _resolve_service(
+    path: Optional[str], service: Optional["MemoryService"]
+) -> "MemoryService":
+    if service is not None:
+        return service
+    if path is None:
+        raise ValueError("make_memory_tools requires either `path` or `service`")
+    return MemoryService(path)
+
+
+def _as_tuples(pairs: Optional[list[list[Any]]]) -> Optional[list[tuple[Any, ...]]]:
+    """``[[a, b, ...], ...]`` -> ``[(a, b, ...), ...]``, or ``None`` if falsy.
+
+    Shared by ``remember``'s ``links`` and ``recall_where``'s ``filters``: both
+    accept plain JSON-friendly lists of lists from the LLM and forward tuples
+    to the binding, which expects ``List[Tuple[...]]``.
+    """
+    if not pairs:
+        return None
+    return [tuple(p) for p in pairs]
+
+
+def _unsupported(method: str) -> dict[str, str]:
+    """Actionable tool-error payload for a ``MemoryService`` method missing on
+    the installed ``velesdb`` (older than this package expects).
+
+    Returned as a normal tool result rather than raised, so a missing method
+    surfaces to the LLM as a tool error it can react to instead of an
+    uncaught ``AttributeError`` that would kill the whole LangGraph run.
+    """
+    return {
+        "error": f"{method} requires velesdb > 3.12.0 — upgrade with `pip install -U velesdb`"
+    }

langgraph_velesdb-4.2.0/src/langgraph_velesdb.egg-info/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: langgraph-velesdb
+Version: 4.2.0
+Summary: LangGraph memory tools for VelesDB: drop the why() knowledge-graph memory wedge into any LangGraph agent.
+Author-email: VelesDB Team <contact@wiscale.fr>
+License: MIT
+Project-URL: Homepage, https://velesdb.com
+Project-URL: Repository, https://github.com/cyberlife-coder/VelesDB
+Keywords: langgraph,langchain,velesdb,agent-memory,knowledge-graph,local-first,why,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langchain-core<2.0.0,>=0.3.0
+Requires-Dist: velesdb>=3.12.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=7.0; extra == "dev"
+Requires-Dist: langgraph>=0.2.0; extra == "dev"
+Dynamic: license-file
+
+# langgraph-velesdb
+
+Drop VelesDB's local-first agent memory — the **`why()` knowledge-graph wedge** —
+into any [LangGraph](https://github.com/langchain-ai/langgraph) agent in three lines.
+
+Most agent memory is vector recall: it finds text that *looks like* the query.
+VelesDB **connects** memories with typed links, so `why()` answers with the
+best-matching memory **plus the connected subgraph** — context that shares no
+words with the question, which a plain vector recall is blind to. The store is on
+disk, so memory persists across agent runs.
+
+![recall() finds the booking but misses the reason; why() reaches it through typed links, across a session restart](https://raw.githubusercontent.com/cyberlife-coder/VelesDB/develop/examples/agent_memory/why_across_sessions.gif)
+
+## Install
+
+```bash
+pip install langgraph-velesdb        # pulls langchain-core + velesdb
+```
+
+## Use
+
+```python
+from langgraph.prebuilt import create_react_agent
+from langgraph_velesdb import make_memory_tools
+
+# Offline by default (hash embedder); pass a configured MemoryService for Ollama.
+agent = create_react_agent(llm, make_memory_tools("./agent_memory"))
+```
+
+`make_memory_tools` returns ten tools the agent can call:
+
+| Tool                   | What it does |
+|------------------------|--------------|
+| `remember`             | store a fact (optionally with `links`, `metadata`, `ttl_seconds`), return its id |
+| `recall`               | semantic (vector) recall — no metadata |
+| `recall_where`         | filtered recall (metadata `[field, op, value]` triples) **with metadata attached**, e.g. the auto `_veles_date` stamp |
+| `recall_fused`         | fused vector + graph recall; pass `date_field="_veles_date"` for a dated timeline |
+| `relate`               | link two memories with a typed edge |
+| `forget`               | delete a memory by id (`True` if it existed, `False` if it was already gone) |
+| `feedback`             | reinforce or weaken a memory after using it, closing the self-improving recall loop |
+| `why`                  | best-matching memory **+ its connected subgraph** (the wedge) |
+| `save_working_context` | persist the current goal/constraints/decisions/pending actions under a project + session |
+| `load_working_context` | resume a prior run's working context — call at the start of a session |
+
+For a pre-configured backend (e.g. Ollama embeddings), build the service yourself
+and pass it through:
+
+```python
+from velesdb import MemoryService
+tools = make_memory_tools(service=MemoryService("./agent_memory"))
+```
+
+### Cross-run resumption
+
+`save_working_context` / `load_working_context` let an agent pick up a task
+across separate runs instead of restarting from scratch:
+
+`make_memory_tools` returns a *list* of tools, so index them by name first
+(the same pattern LangGraph's `ToolNode`/`create_react_agent` use internally):
+
+```python
+tools = {t.name: t for t in make_memory_tools("./agent_memory")}
+
+tools["save_working_context"].invoke({
+    "project": "veles",
+    "session": "issue-1546",
+    "working": {
+        "goal": "ship the langgraph tool set",
+        "pending_actions": ["open the PR"],
+    },
+})
+
+# ... next run, same project + session:
+tools["load_working_context"].invoke({"project": "veles", "session": "issue-1546"})
+```
+
+### Dated recall
+
+Every `remember`-ed fact is auto-stamped with `_veles_date` (today, as a
+`YYYYMMDD` int) unless you set that metadata key yourself. Point
+`recall_fused` at it to get a chronological timeline instead of a ranked list:
+
+```python
+tools = {t.name: t for t in make_memory_tools("./agent_memory")}
+
+tools["recall_fused"].invoke({"query": "what changed this week", "date_field": "_veles_date"})
+# -> {"memories": [...], "dated_context": "...", "now": "..."}
+```
+
+## Compatibility
+
+This package requires `velesdb>=3.12.0`, the highest version published to
+PyPI at the time of writing. `feedback`, `save_working_context`,
+`load_working_context`, and the automatic `_veles_date` metadata stamp landed
+in `velesdb`/`velesdb-memory` *after* the 3.12.0 release cut and are not yet
+in a published wheel. On a plain 3.12.0 install those three tools detect the
+missing binding method at call time and return an error payload instead of
+raising, e.g.:
+
+```json
+{"error": "feedback requires velesdb > 3.12.0 — upgrade with `pip install -U velesdb`"}
+```
+
+so a single unsupported call surfaces to the agent as a normal tool result it
+can react to, instead of an uncaught `AttributeError` killing the whole graph
+run. `recall_where`/`recall_fused` still work, but their `metadata` stays
+empty for auto-dating until you upgrade. `forget` works on 3.12.0 too, but
+returns `None` instead of a `True`/`False` existed-or-not signal. The floor
+will be bumped again once a `velesdb` release past 3.12.0 ships.
+
+`list_working_contexts` (browse saved sessions for a project) is not exposed
+here: it exists on the WASM and MCP surfaces but not yet on the `velesdb`
+Python binding (`MemoryService`), and this package only ever calls the
+binding — no memory logic is reimplemented in this MIT-licensed integration.
+It will be added once the Python binding grows the method.
+
+## License
+
+MIT — see [LICENSE](./LICENSE). Wraps [`velesdb`](https://pypi.org/project/velesdb/),
+which is under the VelesDB Core License 1.0.

langgraph_velesdb-4.2.0/src/langgraph_velesdb.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/langgraph_velesdb/__init__.py
+src/langgraph_velesdb/py.typed
+src/langgraph_velesdb/tools.py
+src/langgraph_velesdb.egg-info/PKG-INFO
+src/langgraph_velesdb.egg-info/SOURCES.txt
+src/langgraph_velesdb.egg-info/dependency_links.txt
+src/langgraph_velesdb.egg-info/requires.txt
+src/langgraph_velesdb.egg-info/top_level.txt
+tests/test_tools.py

langgraph_velesdb-4.2.0/src/langgraph_velesdb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

langgraph_velesdb-4.2.0/src/langgraph_velesdb.egg-info/requires.txt

@@ -0,0 +1,6 @@
+langchain-core<2.0.0,>=0.3.0
+velesdb>=3.12.0
+
+[dev]
+pytest<9.0,>=7.0
+langgraph>=0.2.0

langgraph_velesdb-4.2.0/src/langgraph_velesdb.egg-info/top_level.txt

@@ -0,0 +1 @@
+langgraph_velesdb

langgraph_velesdb-4.2.0/tests/test_tools.py

@@ -0,0 +1,248 @@
+"""Offline tests for the LangGraph memory tools — no LLM, deterministic."""
+
+import tempfile
+
+from langgraph_velesdb import make_memory_tools
+
+
+def _tools_by_name():
+    return {t.name: t for t in make_memory_tools(tempfile.mkdtemp())}
+
+
+class _Pre0_11Service:
+    """Stands in for a ``MemoryService`` built against a velesdb wheel
+    published before ``feedback``/``save_working_context``/
+    ``load_working_context`` existed (e.g. the current PyPI 3.12.0) — same
+    shape as the real binding, minus those three methods.
+    """
+
+    def __init__(self):
+        self._facts = {}
+        self._next_id = 1
+
+    def remember(self, fact, links=None, metadata=None, ttl_seconds=None):
+        fid = self._next_id
+        self._next_id += 1
+        self._facts[fid] = fact
+        return fid
+
+    def recall(self, query, k):
+        return [{"id": i, "score": 1.0, "content": f, "metadata": None} for i, f in self._facts.items()]
+
+    def recall_where(self, query, filters, k):
+        return self.recall(query, k)
+
+    def recall_fused(self, query, k, filter=None, *, date_field=None, options=None):
+        return self.recall(query, k)
+
+    def relate(self, from_id, to_id, relation):
+        return 1
+
+    def forget(self, id):
+        return self._facts.pop(id, None) is not None
+
+    def why(self, question, max_hops):
+        return {"nodes": [], "edges": []}
+
+    # feedback / save_working_context / load_working_context intentionally
+    # absent, matching the real gap on PyPI 3.12.0.
+
+
+def test_exposes_the_full_memory_tool_set():
+    assert set(_tools_by_name()) == {
+        "remember",
+        "recall",
+        "recall_where",
+        "recall_fused",
+        "relate",
+        "forget",
+        "feedback",
+        "why",
+        "save_working_context",
+        "load_working_context",
+    }
+
+
+def test_why_reaches_connected_context_that_recall_misses():
+    tools = _tools_by_name()
+
+    # The booking is the only fact that shares words with the question, so it is
+    # recall's clear top hit; the reason shares none and stays out of the top-1.
+    reason = tools["remember"].invoke(
+        {"fact": "He is recovering from knee surgery and needs to stretch his leg"}
+    )
+    booking = tools["remember"].invoke(
+        {"fact": "Booked the aisle seat on Robert's flight"}
+    )
+    tools["relate"].invoke({"from_id": booking, "to_id": reason, "relation": "because"})
+
+    question = "why the aisle seat on Robert's flight?"
+    recalled = {hit["content"] for hit in tools["recall"].invoke({"query": question, "k": 1})}
+    assert not any("knee surgery" in c for c in recalled)
+
+    reached = {node["content"] for node in tools["why"].invoke({"question": question})["nodes"]}
+    assert any("knee surgery" in c for c in reached)
+
+
+def test_requires_path_or_service():
+    try:
+        make_memory_tools()
+    except ValueError:
+        return
+    raise AssertionError("expected ValueError when neither path nor service is given")
+
+
+def test_forget_removes_a_memory_and_reports_whether_it_existed():
+    tools = _tools_by_name()
+
+    fid = tools["remember"].invoke({"fact": "The deploy key rotates every 90 days"})
+
+    assert tools["forget"].invoke({"memory_id": fid}) is True
+    # Second delete of the same id is a no-op, not an error.
+    assert tools["forget"].invoke({"memory_id": fid}) is False
+
+
+def test_feedback_moves_confidence_after_use():
+    tools = _tools_by_name()
+
+    fid = tools["remember"].invoke({"fact": "Staging uses the blue database"})
+
+    reinforced = tools["feedback"].invoke({"memory_id": fid, "success": True})
+    weakened = tools["feedback"].invoke({"memory_id": fid, "success": False})
+
+    assert 0.0 <= weakened < reinforced <= 1.0
+
+
+def test_remember_accepts_metadata_links_and_ttl_without_changing_defaults():
+    tools = _tools_by_name()
+
+    # Bare call keeps working exactly as before (defaults unchanged).
+    plain_id = tools["remember"].invoke({"fact": "The mascot is a red panda"})
+    assert isinstance(plain_id, int)
+
+    pr = tools["remember"].invoke({"fact": "PR #42 swaps the mutex for parking_lot"})
+    decision = tools["remember"].invoke(
+        {
+            "fact": "We chose parking_lot to avoid lock poisoning",
+            "links": [[pr, "decided_in"]],
+            "metadata": {"topic": "concurrency"},
+            "ttl_seconds": 3600,
+        }
+    )
+
+    hits = tools["recall_where"].invoke(
+        {"query": "parking_lot", "filters": [["topic", "eq", "concurrency"]]}
+    )
+    assert any(h["id"] == decision for h in hits)
+
+
+def test_recall_where_surfaces_metadata_including_the_auto_date_stamp():
+    tools = _tools_by_name()
+
+    tools["remember"].invoke({"fact": "Rotated the signing key"})
+
+    hits = tools["recall_where"].invoke({"query": "signing key", "filters": []})
+
+    assert hits
+    assert "_veles_date" in hits[0]["metadata"]
+
+
+def test_recall_fused_with_date_field_returns_a_dated_timeline():
+    tools = _tools_by_name()
+
+    tools["remember"].invoke({"fact": "Rotated the signing key today"})
+
+    result = tools["recall_fused"].invoke(
+        {"query": "signing key", "date_field": "_veles_date"}
+    )
+
+    assert "dated_context" in result
+    assert "memories" in result
+
+
+def test_recall_fused_without_date_field_returns_a_plain_list():
+    tools = _tools_by_name()
+
+    tools["remember"].invoke({"fact": "Rotated the signing key today"})
+
+    result = tools["recall_fused"].invoke({"query": "signing key"})
+
+    assert isinstance(result, list)
+
+
+def test_save_and_load_working_context_round_trips():
+    tools = _tools_by_name()
+
+    working = {"goal": "ship issue 1546", "pending_actions": ["open the PR"]}
+    tools["save_working_context"].invoke(
+        {"project": "veles", "session": "session-1", "working": working}
+    )
+
+    loaded = tools["load_working_context"].invoke(
+        {"project": "veles", "session": "session-1"}
+    )
+    assert loaded["goal"] == "ship issue 1546"
+
+
+def test_load_working_context_returns_none_when_nothing_was_saved():
+    tools = _tools_by_name()
+
+    loaded = tools["load_working_context"].invoke(
+        {"project": "veles", "session": "no-such-session"}
+    )
+    assert loaded is None
+
+
+def _tools_on_pre_0_11_binding():
+    return {t.name: t for t in make_memory_tools(service=_Pre0_11Service())}
+
+
+def test_make_memory_tools_construction_succeeds_even_without_new_binding_methods():
+    # The guard is a call-time check, not a construction-time one: building
+    # the tool list must not itself require feedback/save_working_context/
+    # load_working_context to exist on the service.
+    tools = _tools_on_pre_0_11_binding()
+    assert set(tools) == {
+        "remember",
+        "recall",
+        "recall_where",
+        "recall_fused",
+        "relate",
+        "forget",
+        "feedback",
+        "why",
+        "save_working_context",
+        "load_working_context",
+    }
+
+
+def test_feedback_returns_actionable_error_instead_of_raising_when_unsupported():
+    tools = _tools_on_pre_0_11_binding()
+
+    result = tools["feedback"].invoke({"memory_id": 1, "success": True})
+
+    assert result == {
+        "error": "feedback requires velesdb > 3.12.0 — upgrade with `pip install -U velesdb`"
+    }
+
+
+def test_save_working_context_returns_actionable_error_instead_of_raising_when_unsupported():
+    tools = _tools_on_pre_0_11_binding()
+
+    result = tools["save_working_context"].invoke(
+        {"project": "veles", "session": "s1", "working": {"goal": "x"}}
+    )
+
+    assert result == {
+        "error": "save_working_context requires velesdb > 3.12.0 — upgrade with `pip install -U velesdb`"
+    }
+
+
+def test_load_working_context_returns_actionable_error_instead_of_raising_when_unsupported():
+    tools = _tools_on_pre_0_11_binding()
+
+    result = tools["load_working_context"].invoke({"project": "veles", "session": "s1"})
+
+    assert result == {
+        "error": "load_working_context requires velesdb > 3.12.0 — upgrade with `pip install -U velesdb`"
+    }