know-do-graph 0.1.0__tar.gz → 0.1.2__tar.gz

know_do_graph-0.1.2/.github/workflows/release-pypi.yml

@@ -0,0 +1,47 @@
+name: Publish PyPI Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install frontend dependencies
+        working-directory: frontend
+        run: npm ci
+
+      - name: Build frontend
+        working-directory: frontend
+        run: npm run build
+
+      - name: Build Python distributions
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

{know_do_graph-0.1.0 → know_do_graph-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: know-do-graph
-Version: 0.1.0
+Version: 0.1.2
 Summary: A wiki-native, agent-oriented infrastructure for executable knowledge, operational memory, and capability discovery.
 Requires-Python: >=3.10
 Requires-Dist: duckduckgo-search>=6.0
@@ -60,6 +60,105 @@ KDG_DB_PATH=./my-data/my-memory.db
 
 Relative `KDG_DB_PATH` values are resolved from the current working directory.
 
+### Python API
+
+Use the high-level client to embed the graph directly in an agent process:
+
+```python
+from know_do_graph import EdgeRelation, EntryType, KnowDoGraph
+
+graph = KnowDoGraph("data/my_agent.db")
+
+skill = graph.add(
+    "Relax an atomic structure",
+    entry_type=EntryType.capability,
+    content="Choose a calculator, then run [[ASE Relaxation]].",
+    tags=["atomistic"],
+)
+procedure = graph.add(
+    "ASE Relaxation",
+    entry_type=EntryType.procedure,
+    content="Attach a calculator and run an ASE optimizer.",
+)
+graph.connect(skill.id, procedure.id, relation=EdgeRelation.decomposes_to)
+
+planner_context = graph.plan("relax this crystal")
+execution_context = graph.expand(skill.slug, stages=["decomposition"])
+
+memory = graph.memory("run-42")
+first = memory.add(
+    "FIRE converged at fmax=0.03.",
+    tags=["success"],
+    success=True,
+)
+second = memory.add("The result reproduced with a tighter force threshold.")
+memory.connect(first.id, second.id)
+graph.close()
+```
+
+The main methods are `add`, `get`, `list`, `search`, `update`, `delete`,
+`connect`, `related`, `plan`, `heuristics`, `constraints`, `expand`, and
+`memory`. IDs, slugs, and aliases are accepted anywhere an entry identifier is
+required. Each client owns its database engine, so multiple graph databases can
+be used safely in the same process.
+
+### Python chat API
+
+Configure an OpenAI or OpenAI-compatible provider:
+
+```bash
+export OPENAI_API_KEY="..."
+export OPENAI_API_BASE="https://your-provider.example/v1"  # optional
+export GRAPH_AGENT_MODEL="qwen-plus"                       # optional
+```
+
+Create a stateful, read-only conversation for question answering:
+
+```python
+from know_do_graph import KnowDoGraph
+
+graph = KnowDoGraph("data/my_agent.db")
+chat = graph.chat(read_only=True, model="qwen-plus")
+
+print(chat.send("Which skills can construct a material interface?"))
+print(chat.send("What constraints apply to the best candidate?"))
+
+chat.reset()
+graph.close()
+```
+
+Allow the agent to add, update, link, and retrieve graph knowledge:
+
+```python
+def on_step(event: str, data: dict) -> None:
+    if event in {"tool_call", "tool_result"}:
+        print(event, data)
+
+with KnowDoGraph("data/my_agent.db") as graph:
+    chat = graph.chat(model="qwen-plus", on_step=on_step)
+    reply = chat.send(
+        "Add a reusable capability for validating atomistic relaxations. "
+        "Search for duplicates and connect it to relevant procedures."
+    )
+    print(reply)
+```
+
+Route a broader task through the orchestrator, or run a review batch:
+
+```python
+with KnowDoGraph("data/my_agent.db") as graph:
+    orchestrator = graph.chat(agent="orchestrator", model="qwen-plus")
+    print(orchestrator.send("Improve weak coverage around phonon workflows."))
+
+    reviewer = graph.chat(agent="reviewer", model="qwen-plus", batch_size=3)
+    print(reviewer.review("Focus on duplicate titles and inconsistent tags."))
+```
+
+Credentials may also be passed directly with `api_key=` and `base_url=`.
+Use `graph.ask("...", read_only=True)` for a one-shot conversation.
+For async applications, call `await asyncio.to_thread(chat.send, message)`.
+See `examples/chat_api.py` for complete examples.
+
 ### Install from source
 
 ```bash
@@ -87,6 +186,35 @@ python main.py serve
 > ```
 > Re-run whenever you edit files under `frontend/src/` or `frontend/styles/`.
 
+### Release to PyPI from GitHub
+
+This repository is set up so the Python package version comes from the Git tag
+used for the release. A GitHub release published from tag `v0.1.1` will build
+package version `0.1.1` and publish it to PyPI automatically.
+
+One-time setup:
+
+1. In PyPI, create a trusted publisher for this repository.
+2. In GitHub, make sure Actions are enabled for the repository.
+3. Publish releases from version tags like `v0.1.1`, `v0.2.0`, and so on.
+
+Release flow:
+
+```bash
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+Then publish a GitHub release for that tag. The workflow at
+`.github/workflows/release-pypi.yml` will:
+
+1. build the frontend assets,
+2. build the Python sdist and wheel,
+3. publish the package to PyPI using GitHub's OIDC trusted publishing.
+
+If you want to test the PyPI connection first, point the same workflow at
+TestPyPI before using the production publisher.
+
 ### Frontend development (hot-reload)
 
 ```bash
@@ -549,7 +677,10 @@ want the `/remote/chat` endpoint to work.
 ## Connecting agent frameworks
 
 MemGraph accepts session data in whichever format the agent framework already
-produces.  Pick the adapter that matches your stack.
+produces. Memory traces are stored in the same SQLite database as all other
+nodes with `entry_type="memory"`. Session and ingestion details are retained in
+entry metadata, and memory nodes can be connected with normal graph edges.
+Pick the adapter that matches your stack.
 
 ### OpenAI / OpenAI-compatible APIs
 
@@ -655,7 +786,7 @@ Supported `entry_type` values: `capability`, `procedure`, `workflow`, `tool`,
 `repository`, `environment`, `dependency`, `data`, `analytical`, `memory`, `generic`.
 
 Supported edge `relation` values: `dependency`, `compatible_with`, `alternative_to`,
-`related_workflow`, `generated_from`, `memory_of`, `refinement_of`, `derived_from`,
+`related_workflow`, `generated_from`, `memory_of`, `related_memory`, `refinement_of`, `derived_from`,
 `warning_about`, `cited_by`, `wikilink`, `prerequisite`, `replacement`,
 `execution_pathway`, `transformation`, `provenance`, `compatibility`.
 
@@ -686,7 +817,7 @@ api/
 
 data/
   know_do_graph.db    Default working SQLite database
-  memory/             Per-session JSON memory files
+  memory/             Legacy JSON memory files (imported into SQLite on first access)
   nodes/              YAML entry exports (via `graph export`)
 
 examples/

{know_do_graph-0.1.0 → know_do_graph-0.1.2}/README.md

@@ -36,6 +36,105 @@ KDG_DB_PATH=./my-data/my-memory.db
 
 Relative `KDG_DB_PATH` values are resolved from the current working directory.
 
+### Python API
+
+Use the high-level client to embed the graph directly in an agent process:
+
+```python
+from know_do_graph import EdgeRelation, EntryType, KnowDoGraph
+
+graph = KnowDoGraph("data/my_agent.db")
+
+skill = graph.add(
+    "Relax an atomic structure",
+    entry_type=EntryType.capability,
+    content="Choose a calculator, then run [[ASE Relaxation]].",
+    tags=["atomistic"],
+)
+procedure = graph.add(
+    "ASE Relaxation",
+    entry_type=EntryType.procedure,
+    content="Attach a calculator and run an ASE optimizer.",
+)
+graph.connect(skill.id, procedure.id, relation=EdgeRelation.decomposes_to)
+
+planner_context = graph.plan("relax this crystal")
+execution_context = graph.expand(skill.slug, stages=["decomposition"])
+
+memory = graph.memory("run-42")
+first = memory.add(
+    "FIRE converged at fmax=0.03.",
+    tags=["success"],
+    success=True,
+)
+second = memory.add("The result reproduced with a tighter force threshold.")
+memory.connect(first.id, second.id)
+graph.close()
+```
+
+The main methods are `add`, `get`, `list`, `search`, `update`, `delete`,
+`connect`, `related`, `plan`, `heuristics`, `constraints`, `expand`, and
+`memory`. IDs, slugs, and aliases are accepted anywhere an entry identifier is
+required. Each client owns its database engine, so multiple graph databases can
+be used safely in the same process.
+
+### Python chat API
+
+Configure an OpenAI or OpenAI-compatible provider:
+
+```bash
+export OPENAI_API_KEY="..."
+export OPENAI_API_BASE="https://your-provider.example/v1"  # optional
+export GRAPH_AGENT_MODEL="qwen-plus"                       # optional
+```
+
+Create a stateful, read-only conversation for question answering:
+
+```python
+from know_do_graph import KnowDoGraph
+
+graph = KnowDoGraph("data/my_agent.db")
+chat = graph.chat(read_only=True, model="qwen-plus")
+
+print(chat.send("Which skills can construct a material interface?"))
+print(chat.send("What constraints apply to the best candidate?"))
+
+chat.reset()
+graph.close()
+```
+
+Allow the agent to add, update, link, and retrieve graph knowledge:
+
+```python
+def on_step(event: str, data: dict) -> None:
+    if event in {"tool_call", "tool_result"}:
+        print(event, data)
+
+with KnowDoGraph("data/my_agent.db") as graph:
+    chat = graph.chat(model="qwen-plus", on_step=on_step)
+    reply = chat.send(
+        "Add a reusable capability for validating atomistic relaxations. "
+        "Search for duplicates and connect it to relevant procedures."
+    )
+    print(reply)
+```
+
+Route a broader task through the orchestrator, or run a review batch:
+
+```python
+with KnowDoGraph("data/my_agent.db") as graph:
+    orchestrator = graph.chat(agent="orchestrator", model="qwen-plus")
+    print(orchestrator.send("Improve weak coverage around phonon workflows."))
+
+    reviewer = graph.chat(agent="reviewer", model="qwen-plus", batch_size=3)
+    print(reviewer.review("Focus on duplicate titles and inconsistent tags."))
+```
+
+Credentials may also be passed directly with `api_key=` and `base_url=`.
+Use `graph.ask("...", read_only=True)` for a one-shot conversation.
+For async applications, call `await asyncio.to_thread(chat.send, message)`.
+See `examples/chat_api.py` for complete examples.
+
 ### Install from source
 
 ```bash
@@ -63,6 +162,35 @@ python main.py serve
 > ```
 > Re-run whenever you edit files under `frontend/src/` or `frontend/styles/`.
 
+### Release to PyPI from GitHub
+
+This repository is set up so the Python package version comes from the Git tag
+used for the release. A GitHub release published from tag `v0.1.1` will build
+package version `0.1.1` and publish it to PyPI automatically.
+
+One-time setup:
+
+1. In PyPI, create a trusted publisher for this repository.
+2. In GitHub, make sure Actions are enabled for the repository.
+3. Publish releases from version tags like `v0.1.1`, `v0.2.0`, and so on.
+
+Release flow:
+
+```bash
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+Then publish a GitHub release for that tag. The workflow at
+`.github/workflows/release-pypi.yml` will:
+
+1. build the frontend assets,
+2. build the Python sdist and wheel,
+3. publish the package to PyPI using GitHub's OIDC trusted publishing.
+
+If you want to test the PyPI connection first, point the same workflow at
+TestPyPI before using the production publisher.
+
 ### Frontend development (hot-reload)
 
 ```bash
@@ -525,7 +653,10 @@ want the `/remote/chat` endpoint to work.
 ## Connecting agent frameworks
 
 MemGraph accepts session data in whichever format the agent framework already
-produces.  Pick the adapter that matches your stack.
+produces. Memory traces are stored in the same SQLite database as all other
+nodes with `entry_type="memory"`. Session and ingestion details are retained in
+entry metadata, and memory nodes can be connected with normal graph edges.
+Pick the adapter that matches your stack.
 
 ### OpenAI / OpenAI-compatible APIs
 
@@ -631,7 +762,7 @@ Supported `entry_type` values: `capability`, `procedure`, `workflow`, `tool`,
 `repository`, `environment`, `dependency`, `data`, `analytical`, `memory`, `generic`.
 
 Supported edge `relation` values: `dependency`, `compatible_with`, `alternative_to`,
-`related_workflow`, `generated_from`, `memory_of`, `refinement_of`, `derived_from`,
+`related_workflow`, `generated_from`, `memory_of`, `related_memory`, `refinement_of`, `derived_from`,
 `warning_about`, `cited_by`, `wikilink`, `prerequisite`, `replacement`,
 `execution_pathway`, `transformation`, `provenance`, `compatibility`.
 
@@ -662,7 +793,7 @@ api/
 
 data/
   know_do_graph.db    Default working SQLite database
-  memory/             Per-session JSON memory files
+  memory/             Legacy JSON memory files (imported into SQLite on first access)
   nodes/              YAML entry exports (via `graph export`)
 
 examples/

{know_do_graph-0.1.0 → know_do_graph-0.1.2}/agents/graph_agent/agent.py

@@ -258,12 +258,14 @@ class GraphAgent:
         model: str | None = None,
         on_step: Callable[[str, dict], None] | None = None,
         read_only: bool = False,
+        api_key: str | None = None,
+        base_url: str | None = None,
     ) -> None:
         self._graph = graph
         self._model = model or os.environ.get("GRAPH_AGENT_MODEL", _DEFAULT_MODEL)
         self._client = OpenAI(
-            api_key=os.environ["OPENAI_API_KEY"],
-            base_url=os.environ.get("OPENAI_API_BASE"),
+            api_key=api_key or os.environ["OPENAI_API_KEY"],
+            base_url=base_url if base_url is not None else os.environ.get("OPENAI_API_BASE"),
         )
         self._read_only = read_only
         system_prompt = _READ_ONLY_SYSTEM_PROMPT if read_only else _SYSTEM_PROMPT

{know_do_graph-0.1.0 → know_do_graph-0.1.2}/agents/graph_agent/tools.py

@@ -38,7 +38,7 @@ def _looks_overly_specific(title: str) -> bool:
     return any(p.search(title) for p in _CONCRETE_INSTANCE_PATTERNS)
 
 
-def _check_generalization(title: str, db: Any) -> dict:
+def _check_generalization(title: str, db: Any, graph: Any = None) -> dict:
     """Soft abstraction check.
 
     Returns ``{needs_generalization: bool, similar: [...], suggestion: str}``.
@@ -49,7 +49,7 @@ def _check_generalization(title: str, db: Any) -> dict:
     from core.retrieval.retrieval import RetrievalEngine
     from core import app_state
 
-    engine = RetrievalEngine(db, app_state.graph)
+    engine = RetrievalEngine(db, graph or app_state.graph)
     candidates = engine.search_entries(query=title, limit=5)
     flag = _looks_overly_specific(title) or len(candidates) > 0
     return {
@@ -85,7 +85,7 @@ def create_entry(
     from core.storage.repository import EntryRepository
 
     with SessionLocal() as db:
-        check = _check_generalization(title, db)
+        check = _check_generalization(title, db, graph)
         meta = EntryMetadata(
             source_provenance=source_provenance,
             needs_generalization=check["needs_generalization"],
@@ -1496,7 +1496,7 @@ TOOL_SCHEMAS: list[dict] = [
                     "relation": {
                         "type": "string",
                         "enum": ["dependency", "compatible_with", "alternative_to", "related_workflow",
-                                 "generated_from", "memory_of", "refinement_of", "derived_from",
+                                 "generated_from", "memory_of", "related_memory", "refinement_of", "derived_from",
                                  "warning_about", "cited_by", "wikilink", "prerequisite", "replacement",
                                  "execution_pathway", "transformation", "provenance", "compatibility",
                                  "implements", "uses", "documents"],

{know_do_graph-0.1.0 → know_do_graph-0.1.2}/agents/maintenance_agent/agent.py

@@ -13,6 +13,7 @@ from pathlib import Path
 from typing import Optional
 
 from core.graph.graph import KnowDoGraph
+from core.schemas.edge import Edge, EdgeRelation
 from core.schemas.entry import Entry, EntryMetadata, EntryType, RefinementStatus
 from core.storage.database import SessionLocal
 from core.storage.repository import EdgeRepository, EntryRepository
@@ -67,10 +68,10 @@ class MaintenanceAgent:
         self,
         mem_id: str,
         session_id: str = "default",
-        entry_type: EntryType = EntryType.memory,
+        entry_type: EntryType = EntryType.generic,
         tags: Optional[list[str]] = None,
     ) -> Optional[Entry]:
-        """Promote a Mem-Graph trace into a full Know-Do Graph entry."""
+        """Distil a raw memory node into a refined graph entry."""
         from core.memory.memgraph import MemGraph
         from core.storage.repository import EntryRepository
 
@@ -93,7 +94,14 @@ class MaintenanceAgent:
 
         with SessionLocal() as db:
             saved = EntryRepository(db).create(entry)
+            edge = EdgeRepository(db).create(Edge(
+                source_id=mem_entry.id,
+                target_id=saved.id,
+                relation=EdgeRelation.refinement_of,
+                metadata={"source": "memory_promotion"},
+            ))
         self._graph.add_entry(saved)
+        self._graph.add_edge(edge)
         mg.mark_promoted(mem_id, saved.id)
         return saved
 

{know_do_graph-0.1.0 → know_do_graph-0.1.2}/agents/orchestrator/agent.py

@@ -71,14 +71,18 @@ class OrchestratorAgent:
         model: str | None = None,
         on_step: Callable[[str, dict], None] | None = None,
         read_only: bool = False,
+        api_key: str | None = None,
+        base_url: str | None = None,
     ) -> None:
         self._graph = graph
         self._model = model or os.environ.get("ORCHESTRATOR_MODEL", os.environ.get("GRAPH_AGENT_MODEL", _DEFAULT_MODEL))
         self._on_step = on_step
         self._read_only = read_only
+        self._api_key = api_key
+        self._base_url = base_url
         self._client = OpenAI(
-            api_key=os.environ["OPENAI_API_KEY"],
-            base_url=os.environ.get("OPENAI_API_BASE"),
+            api_key=api_key or os.environ["OPENAI_API_KEY"],
+            base_url=base_url if base_url is not None else os.environ.get("OPENAI_API_BASE"),
         )
         self._history: list[dict] = [{"role": "system", "content": _SYSTEM_PROMPT}]
 
@@ -122,7 +126,9 @@ class OrchestratorAgent:
                     },
                 },
             },
-            {
+        ]
+        if not self._read_only:
+            tools.append({
                 "type": "function",
                 "function": {
                     "name": "run_review_agent",
@@ -146,8 +152,7 @@ class OrchestratorAgent:
                         },
                     },
                 },
-            },
-        ]
+            })
 
         MAX_ITERATIONS = 8
         for i in range(MAX_ITERATIONS):
@@ -193,6 +198,8 @@ class OrchestratorAgent:
         if name == "run_graph_agent":
             return self._run_graph_agent(kwargs.get("message", ""))
         if name == "run_review_agent":
+            if self._read_only:
+                return "Review agent is not available in read-only mode."
             return self._run_review_agent(
                 kwargs.get("instructions", ""),
                 int(kwargs.get("batch_size", 5)),
@@ -202,7 +209,14 @@ class OrchestratorAgent:
     def _run_graph_agent(self, message: str) -> str:
         from agents.graph_agent.agent import GraphAgent
 
-        agent = GraphAgent(graph=self._graph, model=self._model, on_step=self._on_step, read_only=self._read_only)
+        agent = GraphAgent(
+            graph=self._graph,
+            model=self._model,
+            on_step=self._on_step,
+            read_only=self._read_only,
+            api_key=self._api_key,
+            base_url=self._base_url,
+        )
         return agent.chat(message)
 
     def _run_review_agent(self, instructions: str, batch_size: int) -> str:
@@ -213,5 +227,7 @@ class OrchestratorAgent:
             model=self._model,
             batch_size=batch_size,
             on_step=self._on_step,
+            api_key=self._api_key,
+            base_url=self._base_url,
         )
         return agent.run_review(instructions=instructions)

{know_do_graph-0.1.0 → know_do_graph-0.1.2}/agents/review_agent/agent.py

@@ -90,6 +90,8 @@ class ReviewAgent:
         model: str | None = None,
         batch_size: int = 5,
         on_step: Callable[[str, dict], None] | None = None,
+        api_key: str | None = None,
+        base_url: str | None = None,
     ) -> None:
         self._graph = graph
         self._batch_size = batch_size
@@ -99,8 +101,8 @@ class ReviewAgent:
             os.environ.get("GRAPH_AGENT_MODEL", _DEFAULT_MODEL),
         )
         self._client = OpenAI(
-            api_key=os.environ["OPENAI_API_KEY"],
-            base_url=os.environ.get("OPENAI_API_BASE"),
+            api_key=api_key or os.environ["OPENAI_API_KEY"],
+            base_url=base_url if base_url is not None else os.environ.get("OPENAI_API_BASE"),
         )
 
     # ------------------------------------------------------------------

{know_do_graph-0.1.0 → know_do_graph-0.1.2}/agents/review_agent/tools.py

@@ -433,7 +433,7 @@ REVIEW_TOOL_SCHEMAS: list[dict] = [
                     "relation": {
                         "type": "string",
                         "enum": ["dependency", "compatible_with", "alternative_to", "related_workflow",
-                                 "generated_from", "memory_of", "refinement_of", "derived_from",
+                                 "generated_from", "memory_of", "related_memory", "refinement_of", "derived_from",
                                  "warning_about", "cited_by", "wikilink", "prerequisite", "replacement",
                                  "execution_pathway", "transformation", "provenance", "compatibility"],
                     },

{know_do_graph-0.1.0 → know_do_graph-0.1.2}/api/main.py

@@ -22,6 +22,7 @@ from api.routes import remote_sync as remote_sync_routes
 from api.routes import retrieve as retrieve_routes
 from core.app_state import graph
 from core.storage.database import SessionLocal, init_db
+from core.version import __version__
 
 logger = logging.getLogger(__name__)
 
@@ -74,7 +75,7 @@ app = FastAPI(
         "Agent-facing interface for a wiki-native executable knowledge graph. "
         "Search entries, traverse relations, and navigate operational knowledge."
     ),
-    version="0.1.0",
+    version=__version__,
     lifespan=lifespan,
 )
 

{know_do_graph-0.1.0 → know_do_graph-0.1.2}/api/routes/mem.py

@@ -49,10 +49,18 @@ class RawIngestRequest(BaseModel):
 
 
 class PromoteRequest(BaseModel):
-    entry_type: str = "memory"
+    entry_type: str = "generic"
     tags: list[str] = []
 
 
+class ConnectRequest(BaseModel):
+    source_id: str
+    target_id: str
+    relation: str = "related_memory"
+    weight: float = 1.0
+    metadata: dict[str, Any] = {}
+
+
 # ------------------------------------------------------------------
 # Routes
 # ------------------------------------------------------------------
@@ -158,6 +166,35 @@ def delete_trace(session_id: str, mem_id: str):
         raise HTTPException(status_code=404, detail="Memory trace not found")
 
 
+@router.get("/{session_id}/edges", response_model=list[dict], tags=["mem"])
+def list_memory_edges(session_id: str, mem_id: Optional[str] = None):
+    """List memory-to-memory edges touching nodes in a session."""
+    from core.memory.memgraph import MemGraph
+
+    return [
+        edge.model_dump(mode="json")
+        for edge in MemGraph(session_id).edges(mem_id)
+    ]
+
+
+@router.post("/{session_id}/edges", response_model=dict, status_code=201, tags=["mem"])
+def connect_memory(session_id: str, body: ConnectRequest):
+    """Create a typed edge between two memory nodes."""
+    from core.memory.memgraph import MemGraph
+
+    try:
+        edge = MemGraph(session_id).connect(
+            body.source_id,
+            body.target_id,
+            relation=body.relation,
+            weight=body.weight,
+            metadata=body.metadata,
+        )
+    except (KeyError, ValueError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return edge.model_dump(mode="json")
+
+
 @router.post("/{session_id}/{mem_id}/promote", response_model=dict, tags=["mem"])
 def promote_trace(session_id: str, mem_id: str, body: PromoteRequest):
     """Promote a memory trace into a full Know-Do Graph entry."""