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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: know-do-graph
-Version: 0.1.1
+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
@@ -85,11 +85,14 @@ 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"])
 
-graph.memory("run-42").add(
+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()
 ```
 
@@ -674,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
 
@@ -780,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`.
 
@@ -811,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.1 → know_do_graph-0.1.2}/README.md

@@ -61,11 +61,14 @@ 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"])
 
-graph.memory("run-42").add(
+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()
 ```
 
@@ -650,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
 
@@ -756,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`.
 
@@ -787,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.1 → know_do_graph-0.1.2}/agents/graph_agent/tools.py

@@ -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.1 → 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.1 → 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.1 → 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."""

{know_do_graph-0.1.1 → know_do_graph-0.1.2}/core/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.1'
-__version_tuple__ = version_tuple = (0, 1, 1)
+__version__ = version = '0.1.2'
+__version_tuple__ = version_tuple = (0, 1, 2)
 
 __commit_id__ = commit_id = None

{know_do_graph-0.1.1 → know_do_graph-0.1.2}/core/memory/memgraph.py

@@ -4,7 +4,9 @@ Mem-Graph entries are shallow, episodic notes captured during agent
 interactions.  Over time, stable patterns may be promoted into full
 Know-Do Graph entries.
 
-Storage is flat JSON files per session, kept under data/memory/.
+Memory traces are ordinary Know-Do Graph entries with ``entry_type="memory"``.
+Session-specific fields live in ``EntryMetadata.custom["memory"]`` and links
+between traces are persisted in the shared edges table.
 
 Connecting external agent frameworks
 --------------------------------------
@@ -56,9 +58,15 @@ import uuid
 from datetime import datetime, timezone
 from enum import Enum
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Callable, Optional
 
 from pydantic import BaseModel, Field
+from sqlalchemy.orm import Session
+
+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
 
 def _default_memory_dir() -> Path:
     configured = os.environ.get("KDG_MEMORY_DIR")
@@ -94,14 +102,15 @@ class MemEntry(BaseModel):
 
 
 class MemGraph:
-    """Session-scoped memory graph persisted as a JSON file.
+    """Session-scoped view of memory nodes in the shared graph database.
 
     Parameters
     ----------
     session_id:
-        Logical name for the session.  Determines the storage filename
-        (``data/memory/<session_id>.json``).  Use a stable identifier when
-        you want to resume or extend a session across process restarts.
+        Logical name used to group memory nodes.
+    storage_dir:
+        Deprecated JSON directory. Existing ``<session_id>.json`` files are
+        imported once when the database has no memory nodes for the session.
     """
 
     def __init__(
@@ -109,6 +118,8 @@ class MemGraph:
         session_id: str = "default",
         *,
         storage_dir: str | Path | None = None,
+        session_factory: Callable[[], Session] | None = None,
+        graph: Any = None,
     ) -> None:
         if not session_id or Path(session_id).name != session_id:
             raise ValueError("session_id must be a non-empty filename-safe name")
@@ -118,28 +129,54 @@ class MemGraph:
             if storage_dir is not None
             else _default_memory_dir()
         )
+        self._session_factory = session_factory or SessionLocal
+        if graph is None and session_factory is None:
+            try:
+                from core.app_state import graph as app_graph
+                graph = app_graph
+            except Exception:
+                graph = None
+        self._graph = graph
         self._entries: dict[str, MemEntry] = {}
+        self._ensure_database()
         self._load()
 
     @property
     def _path(self) -> Path:
         return self.storage_dir / f"{self.session_id}.json"
 
+    def _ensure_database(self) -> None:
+        from core.storage.models import Base
+
+        with self._session_factory() as db:
+            Base.metadata.create_all(bind=db.get_bind())
+
     def _load(self) -> None:
-        if self._path.exists():
+        with self._session_factory() as db:
+            entries = [
+                entry
+                for entry in EntryRepository(db).get_all()
+                if entry.entry_type == EntryType.memory
+                and _memory_data(entry).get("session_id") == self.session_id
+            ]
+        self._entries = {entry.id: _entry_to_mem(entry) for entry in entries}
+
+        # Backward-compatible one-time import. JSON remains untouched as a
+        # backup, but is no longer read after the session exists in SQLite.
+        if not self._entries and self._path.exists():
             raw = json.loads(self._path.read_text(encoding="utf-8"))
             self._entries = {k: MemEntry(**v) for k, v in raw.items()}
+            self._save()
 
     def _save(self) -> None:
-        self.storage_dir.mkdir(parents=True, exist_ok=True)
-        self._path.write_text(
-            json.dumps(
-                {k: v.model_dump(mode="json") for k, v in self._entries.items()},
-                indent=2,
-                default=str,
-            ),
-            encoding="utf-8",
-        )
+        with self._session_factory() as db:
+            repo = EntryRepository(db)
+            existing = {entry.id for entry in repo.get_all()}
+            for mem_entry in self._entries.values():
+                entry = _mem_to_entry(mem_entry)
+                saved = repo.update(entry) if entry.id in existing else repo.create(entry)
+                if saved is not None and self._graph is not None:
+                    self._graph.add_entry(saved)
 
     def _make_entry(
         self,
@@ -433,18 +470,98 @@ class MemGraph:
     def delete(self, mem_id: str) -> bool:
         if mem_id not in self._entries:
             return False
+        with self._session_factory() as db:
+            edge_repo = EdgeRepository(db)
+            for edge in edge_repo.get_all():
+                if edge.source_id == mem_id or edge.target_id == mem_id:
+                    edge_repo.delete(edge.id)
+                    if self._graph is not None:
+                        self._graph.remove_edge(edge.source_id, edge.target_id)
+            deleted = EntryRepository(db).delete(mem_id)
+        if not deleted:
+            return False
         del self._entries[mem_id]
-        self._save()
+        if self._graph is not None:
+            self._graph.remove_entry(mem_id)
         return True
 
     @staticmethod
-    def list_sessions(storage_dir: str | Path | None = None) -> list[str]:
-        directory = (
-            Path(storage_dir).expanduser().resolve()
-            if storage_dir is not None
-            else _default_memory_dir()
-        )
-        return sorted(p.stem for p in directory.glob("*.json"))
+    def list_sessions(
+        storage_dir: str | Path | None = None,
+        session_factory: Callable[[], Session] | None = None,
+    ) -> list[str]:
+        factory = session_factory or SessionLocal
+        with factory() as db:
+            from core.storage.models import Base
+            Base.metadata.create_all(bind=db.get_bind())
+            sessions = {
+                _memory_data(entry).get("session_id")
+                for entry in EntryRepository(db).get_all()
+                if entry.entry_type == EntryType.memory
+            }
+        sessions.discard(None)
+
+        # Include legacy sessions so callers can discover and trigger import.
+        directory = Path(storage_dir).expanduser().resolve() if storage_dir else _default_memory_dir()
+        if directory.exists():
+            sessions.update(p.stem for p in directory.glob("*.json"))
+        return sorted(str(session) for session in sessions)
+
+    def connect(
+        self,
+        source_id: str,
+        target_id: str,
+        *,
+        relation: EdgeRelation | str = EdgeRelation.related_memory,
+        weight: float = 1.0,
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> Edge:
+        """Create a typed edge between two memory nodes."""
+        with self._session_factory() as db:
+            entries = {entry.id: entry for entry in EntryRepository(db).get_all()}
+            source = entries.get(source_id)
+            target = entries.get(target_id)
+            if (
+                source is None
+                or target is None
+                or source.entry_type != EntryType.memory
+                or target.entry_type != EntryType.memory
+            ):
+                raise KeyError("Both edge endpoints must be memory nodes")
+            edge = Edge(
+                source_id=source_id,
+                target_id=target_id,
+                relation=EdgeRelation(relation),
+                weight=weight,
+                metadata=metadata or {},
+            )
+            saved = EdgeRepository(db).create(edge)
+        if self._graph is not None:
+            self._graph.add_edge(saved)
+        return saved
+
+    def edges(self, mem_id: str | None = None) -> list[Edge]:
+        """List memory-to-memory edges incident to this session's nodes."""
+        session_ids = set(self._entries)
+        with self._session_factory() as db:
+            memory_ids = {
+                entry.id
+                for entry in EntryRepository(db).get_all()
+                if entry.entry_type == EntryType.memory
+            }
+            edges = [
+                edge
+                for edge in EdgeRepository(db).get_all()
+                if edge.source_id in memory_ids
+                and edge.target_id in memory_ids
+                and (edge.source_id in session_ids or edge.target_id in session_ids)
+            ]
+        if mem_id is not None:
+            edges = [
+                edge for edge in edges
+                if edge.source_id == mem_id or edge.target_id == mem_id
+            ]
+        return edges
 
 
 # ------------------------------------------------------------------
@@ -478,3 +595,54 @@ def _langchain_to_dict(m: Any) -> dict[str, str]:
     role = getattr(m, "type", None) or getattr(m, "role", "unknown")
     content = getattr(m, "content", str(m))
     return {"role": str(role), "content": str(content)}
+
+
+def _memory_data(entry: Entry) -> dict[str, Any]:
+    data = entry.metadata.custom.get("memory", {})
+    return data if isinstance(data, dict) else {}
+
+
+def _entry_to_mem(entry: Entry) -> MemEntry:
+    data = _memory_data(entry)
+    return MemEntry(
+        id=entry.id,
+        session_id=data.get("session_id", "default"),
+        content=entry.content,
+        tags=list(entry.tags),
+        source_entry_ids=list(data.get("source_entry_ids", [])),
+        created_at=entry.metadata.timestamp,
+        success=data.get("success"),
+        promoted=bool(data.get("promoted", False)),
+        promotion_target_id=data.get("promotion_target_id"),
+        source_format=data.get("source_format", MemSourceFormat.manual),
+        raw_source=data.get("raw_source"),
+    )
+
+
+def _mem_to_entry(mem: MemEntry) -> Entry:
+    first_line = next((line.strip("# ").strip() for line in mem.content.splitlines() if line.strip()), "")
+    title = first_line[:80] or f"Memory {mem.id[:8]}"
+    return Entry(
+        id=mem.id,
+        title=title,
+        entry_type=EntryType.memory,
+        content=mem.content,
+        tags=list(mem.tags),
+        metadata=EntryMetadata(
+            timestamp=mem.created_at,
+            source_provenance=f"memory:{mem.session_id}",
+            extraction_method=mem.source_format.value,
+            refinement_status=RefinementStatus.raw,
+            custom={
+                "memory": {
+                    "session_id": mem.session_id,
+                    "source_entry_ids": list(mem.source_entry_ids),
+                    "success": mem.success,
+                    "promoted": mem.promoted,
+                    "promotion_target_id": mem.promotion_target_id,
+                    "source_format": mem.source_format.value,
+                    "raw_source": mem.raw_source,
+                }
+            },
+        ),
+    )

{know_do_graph-0.1.1 → know_do_graph-0.1.2}/core/schemas/edge.py

@@ -14,6 +14,7 @@ class EdgeRelation(str, Enum):
     related_workflow = "related_workflow"
     generated_from = "generated_from"
     memory_of = "memory_of"
+    related_memory = "related_memory"
     refinement_of = "refinement_of"
     derived_from = "derived_from"
     warning_about = "warning_about"

{know_do_graph-0.1.1 → know_do_graph-0.1.2}/know_do_graph/client.py

@@ -238,8 +238,13 @@ class KnowDoGraph:
             )
 
     def memory(self, session_id: str = "default") -> MemGraph:
-        """Return session-scoped episodic memory stored beside this database."""
-        return MemGraph(session_id, storage_dir=self.memory_dir)
+        """Return a session-scoped view of memory nodes in this graph."""
+        return MemGraph(
+            session_id,
+            storage_dir=self.memory_dir,
+            session_factory=self._session_factory,
+            graph=self._graph,
+        )
 
     def chat(
         self,

{know_do_graph-0.1.1 → know_do_graph-0.1.2}/main.py

@@ -388,7 +388,7 @@ def mem_list(
 def mem_promote(
     mem_id: str = typer.Argument(..., help="Memory trace ID"),
     session: str = typer.Option("default", "--session"),
-    entry_type: str = typer.Option("memory", "--type", "-t"),
+    entry_type: str = typer.Option("generic", "--type", "-t"),
 ) -> None:
     """Promote a Mem-Graph trace into a full Know-Do Graph entry."""
     _init()

{know_do_graph-0.1.1 → know_do_graph-0.1.2}/tests/test_public_api.py

@@ -74,7 +74,13 @@ class PublicApiTests(unittest.TestCase):
         memory = self.graph.memory("agent-run")
         trace = memory.add("The low-strain match succeeded.", success=True)
         self.assertEqual(memory.get(trace.id).content, trace.content)
-        self.assertTrue((self.graph.memory_dir / "agent-run.json").is_file())
+        self.assertEqual(self.graph.get(trace.id).entry_type, EntryType.memory)
+        self.assertFalse((self.graph.memory_dir / "agent-run.json").exists())
+
+        follow_up = memory.add("The result reproduced on a second structure.")
+        edge = memory.connect(trace.id, follow_up.id)
+        self.assertEqual(edge.relation, EdgeRelation.related_memory)
+        self.assertEqual(memory.edges(trace.id)[0].target_id, follow_up.id)
 
     def test_clients_are_isolated_by_database_path(self) -> None:
         other_path = Path(self.temp_dir.name) / "other.db"