{
  "kind": "documentation",
  "format": 1,
  "note": "Reference text, not instructions. One verified relate sample from https://relatedb.ai/docs/guides/integrations/langchain/: the program exactly as the page shows it, the standard output a run of it recorded (npm run docs:samples compares every replay with it byte for byte), the relate client build, toolchain and platform of the last replay, and how the docs' sample runner builds and runs it. Before launch every client is a source build, not a published package; verified.client names the upstream commit it was built from, and verified.docs_engine the build the rest of the docs were recorded from.",
  "id": "recall-tool",
  "url": "https://relatedb.ai/docs/guides/integrations/langchain/samples/recall-tool.json",
  "page": {
    "id": "guides/integrations/langchain",
    "title": "Use relate with LangChain",
    "url": "https://relatedb.ai/docs/guides/integrations/langchain/",
    "md_url": "https://relatedb.ai/docs/guides/integrations/langchain.md"
  },
  "section": {
    "anchor": "write-the-tool",
    "heading": "Write the tool",
    "url": "https://relatedb.ai/docs/guides/integrations/langchain/#write-the-tool"
  },
  "language": "python",
  "client": "Python",
  "file": "recall_tool.py",
  "env": null,
  "code": "import relate\nfrom langchain.tools import ToolException, tool\n\nTEAM = \"\"\"\nCREATE (ada:Person {name: 'Ada', role: 'engineer'}),\n       (grace:Person {name: 'Grace', role: 'engineer'}),\n       (noor:Person {name: 'Noor', role: 'maintainer'}),\n       (relate:Project {name: 'relate', language: 'Rust'}),\n       (tck:Project {name: 'opencypher-tck', language: 'Gherkin'}),\n       (ada)-[:WORKS_ON {since: 2024}]->(relate),\n       (grace)-[:WORKS_ON {since: 2023}]->(relate),\n       (grace)-[:WORKS_ON {since: 2022}]->(tck),\n       (noor)-[:MAINTAINS]->(relate),\n       (ada)-[:KNOWS]->(grace)\n\"\"\"\n\nREMEMBER = \"\"\"\nMERGE (c:Conversation {id: $conversation})\nCREATE (e:Episode {seq: $seq, text: $text})-[:IN_CONVERSATION]->(c)\nWITH e\nUNWIND $mentions AS name\nMATCH (x {name: name})\nMERGE (e)-[:MENTIONS]->(x)\n\"\"\"\n\nSTORE = \"./memory\"\n\n# Setup: the app that owns ./memory writes the team graph and two episodes, on a writable connection.\nwith relate.connect(STORE) as owner:\n    if owner.execute(\"MATCH (p:Person) RETURN count(p) AS n\").single()[\"n\"] == 0:\n        owner.execute(TEAM)\n        owner.execute(REMEMBER, {\"conversation\": \"standup-monday\", \"seq\": 1, \"text\": \"Ada fixed the CSV import bug in relate.\", \"mentions\": [\"Ada\", \"relate\"]})\n        owner.execute(REMEMBER, {\"conversation\": \"standup-tuesday\", \"seq\": 2, \"text\": \"Grace will review the relate release notes.\", \"mentions\": [\"Grace\", \"relate\"]})\n\n\n@tool(parse_docstring=True)\ndef recall(name: str) -> list[str]:\n    \"\"\"Return what memory holds about a person or project: the episodes that mention it, oldest first, then who works on it.\n\n    Args:\n        name: The exact name of a person or project, such as \"Ada\" or \"relate\".\n    \"\"\"\n    # Read-only: the engine refuses every write on this connection.\n    with relate.connect(STORE, read_only=True) as conn:\n        if conn.execute(\"MATCH (x {name: $name}) RETURN count(x) AS n\", {\"name\": name}).single()[\"n\"] == 0:\n            raise ToolException(f\"Nothing in memory is named {name!r}.\")\n        episodes = conn.execute(\n            \"\"\"\n            MATCH (x {name: $name})<-[:MENTIONS]-(e:Episode)-[:IN_CONVERSATION]->(c:Conversation)\n            RETURN c.id AS conversation, e.text AS text\n            ORDER BY e.seq\n            \"\"\",\n            {\"name\": name},\n        ).fetchall()\n        people = conn.execute(\n            \"\"\"\n            MATCH (x {name: $name})<-[w:WORKS_ON]-(p:Person)\n            RETURN p.name AS person, w.since AS since\n            ORDER BY since\n            \"\"\",\n            {\"name\": name},\n        ).fetchall()\n    return [f\"[{r['conversation']}] {r['text']}\" for r in episodes] + [\n        f\"{r['person']} has worked on {name} since {r['since']}\" for r in people\n    ]\n\n\n# A ToolException goes back to the model as the tool's answer instead of ending the run.\nrecall.handle_tool_error = True\n\n# Check: what the model sees, then two calls the way an agent makes them.\nprint(recall.name, recall.args)\nfor line in recall.invoke({\"name\": \"relate\"}):\n    print(line)\nprint(recall.invoke({\"name\": \"relate-engine\"}))",
  "code_sha256": "1ea0887477e74e5d0b89b4c6087d25fd5e1447901869268fd3d4e32441f044b9",
  "source_sha256": "041aba2688b4e54b887d4190a23490c160a009bcc31aa1d88abc1abca6328a92",
  "output": {
    "text": "recall {'name': {'description': 'The exact name of a person or project, such as \"Ada\" or \"relate\".', 'title': 'Name', 'type': 'string'}}\n[standup-monday] Ada fixed the CSV import bug in relate.\n[standup-tuesday] Grace will review the relate release notes.\nGrace has worked on relate since 2023\nAda has worked on relate since 2024\nNothing in memory is named 'relate-engine'.",
    "sha256": "5b334af1b849f333d30bc1abea0331d683e828586c95f3150c556e83a4d9291a"
  },
  "verified": {
    "version": "0.1.2",
    "client": {
      "label": "Python",
      "package": "relate-db",
      "engine_commit": "f0c09d2",
      "client_commit": "f0c09d2",
      "build": "A relate-db wheel that maturin built from surfaces/relate-python at upstream v0.1.2 (f0c09d2), installed in a venv with the pinned frameworks.",
      "toolchain": {
        "python": "3.15.2"
      }
    },
    "packages": [
      "pandas>=2.0",
      "langgraph==1.2.20",
      "claude-agent-sdk==0.2.179",
      "pydantic-ai==2.66.0",
      "openai-agents==0.24.0",
      "llama-index-core==0.14.25",
      "langchain==1.4.9",
      "langchain-core==1.7.6"
    ],
    "replayed": "2026-11-09",
    "platform": "macOS on arm64",
    "docs_engine": {
      "version": "0.1.2",
      "commit": "f0c09d2",
      "source_build": false
    }
  },
  "run": {
    "runner": "npm run docs:samples",
    "setup": "bash scripts/samples/setup.sh --upstream <path to the relate checkout>",
    "variables": [
      "RELATE_PY"
    ],
    "program": "<run dir>/recall_tool.py",
    "files": [],
    "build": null,
    "run": {
      "command": [
        "$RELATE_PY",
        "recall_tool.py"
      ],
      "environment": {
        "DO_NOT_TRACK": "1",
        "PYTHONDONTWRITEBYTECODE": "1",
        "PYTHONUNBUFFERED": "1"
      },
      "directory": "<run dir>",
      "timeout_s": 60
    },
    "passes": "It exits 0 within 60 s and prints at least one line on standard output.",
    "output": "Standard output, with line endings as \\n, trailing spaces and blank lines removed, and the temporary directories' paths written as `.`; standard error is not recorded.",
    "placeholders": {
      "<run dir>": "a fresh, empty temporary directory: the program's working directory, deleted afterwards",
      "<build dir>": "a second fresh temporary directory, where a compiled sample is built",
      "$NAME": "a variable from the env.sh that scripts/samples/setup.sh writes (described in its header)"
    }
  }
}