feat: Graph API 확장 — list/update/maintain/add_turn + 커스텀 NodeKind (v0.8.0)

사용자 피드백 5건 반영:
1. graph.list(kind=, level=, limit=) — 전체 노드 조회 + 필터링
2. graph.update(node_id, title=, content=, ...) — 노드 부분 업데이트
3. MaintenanceResult + graph.maintain() — consolidate+decay+prune 통합 (기존 API 유지)
4. graph.add_turn(user_msg, asst_msg, session_id=) — 대화 세션/턴 헬퍼
5. Node.kind를 str로 확장 — 커스텀 kind("culture", "preference" 등) 자유 사용
   - 전 backend _safe_node_kind() 헬퍼로 DB 저장/복원 안전 처리

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: SonAIengine

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "synaptic-memory"
-version = "0.7.0"
+version = "0.8.0"
 description = "Brain-inspired knowledge graph for LLM agents — PPR, evidence chain, auto-ontology (rule/embedding/LLM), Hebbian learning, memory consolidation."
 license = "MIT"
 requires-python = ">=3.12"

src/synaptic/__init__.py

@@ -60,6 +60,7 @@
     EdgeKind,
     EvidenceChain,
     EvidenceStep,
+    MaintenanceResult,
     Node,
     NodeKind,
     SearchResult,
@@ -82,7 +83,7 @@
 )
 from synaptic.resonance import ResonanceWeights
 
-__version__ = "0.6.0"
+__version__ = "0.8.0"
 
 __all__ = [
     "ActivatedNode",
@@ -100,6 +101,7 @@
     "EmbeddingRelationDetector",
     "GraphTraversal",
     "KindClassifier",
+    "MaintenanceResult",
     "MockEmbeddingProvider",
     "Node",
     "NodeKind",

src/synaptic/backends/composite.py

@@ -147,7 +147,7 @@ async def delete_node(self, node_id: str) -> None:
     async def list_nodes(
         self,
         *,
-        kind: NodeKind | None = None,
+        kind: str | NodeKind | None = None,
         level: ConsolidationLevel | None = None,
         limit: int = 100,
     ) -> list[Node]:

src/synaptic/backends/memory.py

@@ -55,7 +55,7 @@ async def delete_node(self, node_id: str) -> None:
     async def list_nodes(
         self,
         *,
-        kind: NodeKind | None = None,
+        kind: str | NodeKind | None = None,
         level: ConsolidationLevel | None = None,
         limit: int = 100,
     ) -> list[Node]:

src/synaptic/backends/neo4j.py

@@ -143,7 +143,7 @@ async def delete_node(self, node_id: str) -> None:
     async def list_nodes(
         self,
         *,
-        kind: NodeKind | None = None,
+        kind: str | NodeKind | None = None,
         level: ConsolidationLevel | None = None,
         limit: int = 100,
     ) -> list[Node]:
@@ -481,14 +481,22 @@ def _node_to_props(node: Node) -> dict[str, object]:
     }
 
 
+def _safe_node_kind(value: str) -> str | NodeKind:
+    """Convert to NodeKind if known, otherwise keep as raw string."""
+    try:
+        return NodeKind(value)
+    except ValueError:
+        return value
+
+
 def _record_to_node(data: object) -> Node:
     """Convert Neo4j node record to Node dataclass."""
     # neo4j driver returns dict-like objects
     d: dict[str, object] = dict(data) if not isinstance(data, dict) else data  # type: ignore[arg-type]
     props_raw = d.get("properties_json", "{}")
     return Node(
         id=str(d.get("id", "")),
-        kind=NodeKind(str(d.get("kind", "concept"))),
+        kind=_safe_node_kind(str(d.get("kind", "concept"))),
         title=str(d.get("title", "")),
         content=str(d.get("content", "")),
         tags=json.loads(str(d.get("tags_json", "[]"))),

src/synaptic/backends/postgresql.py

@@ -213,7 +213,7 @@ async def delete_node(self, node_id: str) -> None:
     async def list_nodes(
         self,
         *,
-        kind: NodeKind | None = None,
+        kind: str | NodeKind | None = None,
         level: ConsolidationLevel | None = None,
         limit: int = 100,
     ) -> list[Node]:
@@ -441,12 +441,20 @@ async def decay_vitality(self, *, factor: float = 0.95) -> int:
         return int(result.split()[-1]) if result else 0
 
 
+def _safe_node_kind(value: str) -> str | NodeKind:
+    """Convert to NodeKind if known, otherwise keep as raw string."""
+    try:
+        return NodeKind(value)
+    except ValueError:
+        return value
+
+
 def _row_to_node(row: asyncpg.Record) -> Node:
     tags = list(row["tags"]) if row["tags"] else []
     props_raw = row.get("properties_json", "{}")
     return Node(
         id=row["id"],
-        kind=NodeKind(row["kind"]),
+        kind=_safe_node_kind(row["kind"]),
         title=row["title"],
         content=row["content"],
         tags=tags,

src/synaptic/backends/sqlite.py

@@ -180,7 +180,7 @@ async def delete_node(self, node_id: str) -> None:
     async def list_nodes(
         self,
         *,
-        kind: NodeKind | None = None,
+        kind: str | NodeKind | None = None,
         level: ConsolidationLevel | None = None,
         limit: int = 100,
     ) -> list[Node]:
@@ -359,11 +359,19 @@ async def decay_vitality(self, *, factor: float = 0.95) -> int:
         return int(count)
 
 
+def _safe_node_kind(value: str) -> str | NodeKind:
+    """Convert to NodeKind if known, otherwise keep as raw string."""
+    try:
+        return NodeKind(value)
+    except ValueError:
+        return value
+
+
 def _row_to_node(row: aiosqlite.Row) -> Node:
     props_raw = row["properties_json"] if "properties_json" in row.keys() else "{}"
     return Node(
         id=row["id"],
-        kind=NodeKind(row["kind"]),
+        kind=_safe_node_kind(row["kind"]),
         title=row["title"],
         content=row["content"],
         tags=json.loads(row["tags_json"]),

src/synaptic/graph.py

@@ -21,6 +21,7 @@
     Edge,
     EdgeKind,
     EvidenceChain,
+    MaintenanceResult,
     Node,
     NodeKind,
     SearchResult,
@@ -229,7 +230,7 @@ async def add(
         title: str,
         content: str,
         *,
-        kind: NodeKind | None = None,
+        kind: str | NodeKind | None = None,
         tags: list[str] | None = None,
         source: str = "",
         embedding: list[float] | None = None,
@@ -363,6 +364,16 @@ async def agent_search(
             depth=depth,
         )
 
+    async def list(
+        self,
+        *,
+        kind: str | NodeKind | None = None,
+        level: ConsolidationLevel | None = None,
+        limit: int = 100,
+    ) -> list[Node]:
+        """List all nodes with optional kind/level filtering."""
+        return await self._backend.list_nodes(kind=kind, level=level, limit=limit)
+
     async def get(self, node_id: str) -> Node | None:
         cached = self._cache.get(node_id)
         if cached is not None:
@@ -376,6 +387,39 @@ async def get(self, node_id: str) -> Node | None:
             self._cache.put(node)
         return node
 
+    async def update(
+        self,
+        node_id: str,
+        *,
+        title: str | None = None,
+        content: str | None = None,
+        kind: str | NodeKind | None = None,
+        tags: list[str] | None = None,
+        properties: dict[str, str] | None = None,
+        embedding: list[float] | None = None,
+    ) -> Node | None:
+        """Update a node's fields by ID. Returns updated node, or None if not found."""
+        node = await self._backend.get_node(node_id)
+        if node is None:
+            return None
+        if title is not None:
+            node.title = title
+        if content is not None:
+            node.content = content
+        if kind is not None:
+            node.kind = kind
+        if tags is not None:
+            node.tags = tags
+        if properties is not None:
+            node.properties = properties
+        if embedding is not None:
+            node.embedding = embedding
+        node.updated_at = time()
+        await self._backend.update_node(node)
+        self._cache.invalidate(node_id)
+        self._cache.put(node)
+        return node
+
     async def remove(self, node_id: str) -> bool:
         node = await self._backend.get_node(node_id)
         if node is None:
@@ -408,6 +452,20 @@ async def decay(self) -> int:
         self._cache.clear()  # Vitality changed globally
         return await self._backend.decay_vitality(factor=0.95)
 
+    async def maintain(
+        self,
+        digester: Digester | None = None,
+        *,
+        context: dict[str, object] | None = None,
+    ) -> MaintenanceResult:
+        """Run consolidate + decay + prune in one call with a unified result."""
+        consolidated = await self._consolidation.consolidate(
+            self._backend, digester, context=context,
+        )
+        decayed = await self.decay()
+        pruned = await self.prune()
+        return MaintenanceResult(consolidated=consolidated, decayed=decayed, pruned=pruned)
+
     async def export_markdown(self, *, node_ids: list[str] | None = None) -> str:
         return await self._md_exporter.export(self._backend, node_ids=node_ids)
 
@@ -537,6 +595,79 @@ async def build_evidence(
             self._backend, query, search_result, max_steps=max_steps,
         )
 
+    # --- Conversation helpers ---
+
+    async def add_turn(
+        self,
+        user_msg: str,
+        assistant_msg: str,
+        *,
+        session_id: str | None = None,
+        tags: list[str] | None = None,
+    ) -> tuple[Node, Node, Node]:
+        """Add a conversation turn (user + assistant) linked to a session.
+
+        Creates a SESSION node on first call for a given session_id.
+        Returns (session_node, user_node, assistant_node).
+        """
+        from synaptic.models import _new_id  # noqa: PLC0415
+
+        if session_id is None:
+            session_id = f"session_{_new_id()}"
+
+        # Get or create session node
+        session_node = await self._backend.get_node(session_id)
+        if session_node is None:
+            session_node = await self._store.add_node(
+                f"Session {session_id[:8]}",
+                "",
+                kind=NodeKind.SESSION,
+                tags=["_session"],
+                source=session_id,
+            )
+            # Override the auto-generated ID with session_id
+            await self._backend.delete_node(session_node.id)
+            session_node.id = session_id
+            await self._backend.save_node(session_node)
+
+        turn_tags = [*tags] if tags else []
+
+        # Create user message node
+        user_node = await self._store.add_node(
+            "user", user_msg, kind=NodeKind.OBSERVATION, tags=[*turn_tags, "_turn_user"],
+        )
+
+        # Create assistant message node
+        assistant_node = await self._store.add_node(
+            "assistant", assistant_msg, kind=NodeKind.OBSERVATION, tags=[*turn_tags, "_turn_assistant"],
+        )
+
+        # Link: user → assistant (FOLLOWED_BY)
+        await self._store.add_edge(
+            user_node.id, assistant_node.id, kind=EdgeKind.FOLLOWED_BY,
+        )
+
+        # Link: session → user (CONTAINS)
+        await self._store.add_edge(
+            session_id, user_node.id, kind=EdgeKind.CONTAINS,
+        )
+
+        # Link last turn to this one (FOLLOWED_BY)
+        session_edges = await self._backend.get_edges(session_id, direction="outgoing")
+        contained = [e for e in session_edges if e.kind == EdgeKind.CONTAINS and e.target_id != user_node.id]
+        if contained:
+            # Find the most recent contained user node
+            last_user_id = contained[-1].target_id
+            # Get the assistant node linked from last user
+            last_edges = await self._backend.get_edges(last_user_id, direction="outgoing")
+            last_assistant = [e for e in last_edges if e.kind == EdgeKind.FOLLOWED_BY]
+            if last_assistant:
+                await self._store.add_edge(
+                    last_assistant[-1].target_id, user_node.id, kind=EdgeKind.FOLLOWED_BY,
+                )
+
+        return session_node, user_node, assistant_node
+
     # --- Ontology persistence ---
 
     async def save_ontology(self) -> None:

src/synaptic/models.py

@@ -68,7 +68,7 @@ class EdgeKind(StrEnum):
 @dataclass(slots=True)
 class Node:
     id: str = field(default_factory=_new_id)
-    kind: NodeKind = NodeKind.CONCEPT
+    kind: str = NodeKind.CONCEPT
     title: str = ""
     content: str = ""
     tags: list[str] = field(default_factory=_str_list)
@@ -131,6 +131,21 @@ class DigestResult:
     tokens_used: int = 0
 
 
+@dataclass(slots=True)
+class MaintenanceResult:
+    """Unified result for maintenance operations (consolidate + decay + prune)."""
+    consolidated: DigestResult | None = None
+    decayed: int = 0
+    pruned: int = 0
+
+    @property
+    def total_affected(self) -> int:
+        count = self.decayed + self.pruned
+        if self.consolidated:
+            count += len(self.consolidated.nodes_created) + len(self.consolidated.nodes_updated)
+        return count
+
+
 def _evidence_step_list() -> list["EvidenceStep"]:
     return []
 

src/synaptic/protocols.py

@@ -30,7 +30,7 @@ async def delete_node(self, node_id: str) -> None: ...
     async def list_nodes(
         self,
         *,
-        kind: NodeKind | None = None,
+        kind: str | NodeKind | None = None,
         level: ConsolidationLevel | None = None,
         limit: int = 100,
     ) -> list[Node]: ...