feat: synaptic-memory v0.1.0 — 뇌 신경망 기반 knowledge graph 라이브러리

핵심 모듈:
- models: Node/Edge/ActivatedNode + ConsolidationLevel(L0→L3) + NodeKind 9종
- protocols: StorageBackend/Digester/QueryRewriter/TagExtractor Protocol
- graph: SynapticGraph facade (add/link/search/reinforce/consolidate/prune/decay)
- search: 3단계 하이브리드 검색 (FTS+fuzzy+vector → 동의어 확장 → query rewrite)
- hebbian: Hebbian learning — 성공/실패 기반 edge weight 자동 조정
- resonance: 4축 scoring (relevance × importance × recency × vitality)
- consolidation: L0→L3 메모리 압축 캐스케이드 (TTL + 사용빈도 승격)
- synonyms: 한/영 동의어 맵 (30+ 그룹)
- exporter: Markdown 내보내기

백엔드:
- MemoryBackend: dict 기반 in-memory (테스트용)
- SQLiteBackend: FTS5 + recursive CTE 그래프 순회
- PostgreSQLBackend: stub (v0.2.0 예정 — AGE + pgvector + pg_trgm)

Zero core deps — 백엔드만 extras (sqlite/postgresql)
93 tests passed, pyright strict 0 errors

Author: SonAIengine

pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "synaptic-memory"
+version = "0.1.0"
+description = "Brain-inspired knowledge graph: spreading activation, Hebbian learning, memory consolidation."
+license = "MIT"
+requires-python = ">=3.12"
+authors = [{ name = "Son Seongjun" }]
+dependencies = []
+
+[project.optional-dependencies]
+postgresql = ["asyncpg>=0.30", "pgvector>=0.3"]
+sqlite = ["aiosqlite>=0.20"]
+all = ["asyncpg>=0.30", "pgvector>=0.3", "aiosqlite>=0.20"]
+dev = ["pytest>=8.3", "pytest-asyncio>=0.24", "ruff>=0.8", "pyright>=1.1"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/synaptic"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "A", "S", "ASYNC", "PLC", "RUF"]
+ignore = ["S101"]
+
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"

src/synaptic/__init__.py

@@ -0,0 +1,30 @@
+"""Synaptic Memory — Brain-inspired knowledge graph."""
+
+from synaptic.graph import SynapticGraph
+from synaptic.models import (
+    ActivatedNode,
+    ConsolidationLevel,
+    DigestResult,
+    Edge,
+    EdgeKind,
+    Node,
+    NodeKind,
+    SearchResult,
+)
+from synaptic.protocols import Digester, QueryRewriter, StorageBackend, TagExtractor
+
+__all__ = [
+    "ActivatedNode",
+    "ConsolidationLevel",
+    "DigestResult",
+    "Digester",
+    "Edge",
+    "EdgeKind",
+    "Node",
+    "NodeKind",
+    "QueryRewriter",
+    "SearchResult",
+    "StorageBackend",
+    "SynapticGraph",
+    "TagExtractor",
+]

src/synaptic/backends/__init__.py

@@ -0,0 +1 @@
+"""Storage backends for Synaptic Memory."""

src/synaptic/backends/memory.py

@@ -0,0 +1,193 @@
+"""In-memory storage backend for testing."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from difflib import SequenceMatcher
+
+from synaptic.models import (
+    ConsolidationLevel,
+    Edge,
+    Node,
+    NodeKind,
+)
+
+
+class MemoryBackend:
+    """Dict-based in-memory backend. No external dependencies."""
+
+    __slots__ = ("_edges", "_nodes")
+
+    def __init__(self) -> None:
+        self._nodes: dict[str, Node] = {}
+        self._edges: dict[str, Edge] = {}
+
+    async def connect(self) -> None:
+        pass
+
+    async def close(self) -> None:
+        self._nodes.clear()
+        self._edges.clear()
+
+    # --- Node CRUD ---
+
+    async def save_node(self, node: Node) -> None:
+        self._nodes[node.id] = node
+
+    async def get_node(self, node_id: str) -> Node | None:
+        return self._nodes.get(node_id)
+
+    async def update_node(self, node: Node) -> None:
+        if node.id in self._nodes:
+            self._nodes[node.id] = node
+
+    async def delete_node(self, node_id: str) -> None:
+        self._nodes.pop(node_id, None)
+        # Cascade delete edges
+        to_delete = [
+            eid
+            for eid, e in self._edges.items()
+            if e.source_id == node_id or e.target_id == node_id
+        ]
+        for eid in to_delete:
+            del self._edges[eid]
+
+    async def list_nodes(
+        self,
+        *,
+        kind: NodeKind | None = None,
+        level: ConsolidationLevel | None = None,
+        limit: int = 100,
+    ) -> list[Node]:
+        result: list[Node] = []
+        for node in self._nodes.values():
+            if kind is not None and node.kind != kind:
+                continue
+            if level is not None and node.level != level:
+                continue
+            result.append(node)
+            if len(result) >= limit:
+                break
+        return result
+
+    # --- Edge CRUD ---
+
+    async def save_edge(self, edge: Edge) -> None:
+        self._edges[edge.id] = edge
+
+    async def get_edges(self, node_id: str, *, direction: str = "both") -> list[Edge]:
+        result: list[Edge] = []
+        for edge in self._edges.values():
+            if direction in ("both", "outgoing") and edge.source_id == node_id:
+                result.append(edge)
+            elif direction in ("both", "incoming") and edge.target_id == node_id:
+                result.append(edge)
+        return result
+
+    async def update_edge(self, edge: Edge) -> None:
+        if edge.id in self._edges:
+            self._edges[edge.id] = edge
+
+    async def delete_edge(self, edge_id: str) -> None:
+        self._edges.pop(edge_id, None)
+
+    # --- Search ---
+
+    async def search_fts(self, query: str, *, limit: int = 20) -> list[Node]:
+        query_lower = query.lower()
+        terms = query_lower.split()
+        scored: list[tuple[Node, int]] = []
+        for node in self._nodes.values():
+            text = f"{node.title} {node.content}".lower()
+            hits = sum(1 for t in terms if t in text)
+            if hits > 0:
+                scored.append((node, hits))
+        scored.sort(key=lambda x: x[1], reverse=True)
+        return [n for n, _ in scored[:limit]]
+
+    async def search_fuzzy(
+        self, query: str, *, limit: int = 20, threshold: float = 0.3
+    ) -> list[Node]:
+        scored: list[tuple[Node, float]] = []
+        for node in self._nodes.values():
+            text = f"{node.title} {node.content}"
+            ratio = SequenceMatcher(None, query.lower(), text.lower()).ratio()
+            if ratio >= threshold:
+                scored.append((node, ratio))
+        scored.sort(key=lambda x: x[1], reverse=True)
+        return [n for n, _ in scored[:limit]]
+
+    async def search_vector(self, embedding: list[float], *, limit: int = 20) -> list[Node]:
+        if not embedding:
+            return []
+        scored: list[tuple[Node, float]] = []
+        for node in self._nodes.values():
+            if not node.embedding:
+                continue
+            sim = _cosine_similarity(embedding, node.embedding)
+            scored.append((node, sim))
+        scored.sort(key=lambda x: x[1], reverse=True)
+        return [n for n, _ in scored[:limit]]
+
+    # --- Graph traversal ---
+
+    async def get_neighbors(self, node_id: str, *, depth: int = 1) -> list[tuple[Node, Edge]]:
+        result: list[tuple[Node, Edge]] = []
+        visited: set[str] = {node_id}
+        frontier: set[str] = {node_id}
+
+        for _ in range(depth):
+            next_frontier: set[str] = set()
+            for nid in frontier:
+                for edge in self._edges.values():
+                    neighbor_id: str | None = None
+                    if edge.source_id == nid and edge.target_id not in visited:
+                        neighbor_id = edge.target_id
+                    elif edge.target_id == nid and edge.source_id not in visited:
+                        neighbor_id = edge.source_id
+
+                    if neighbor_id is not None:
+                        neighbor = self._nodes.get(neighbor_id)
+                        if neighbor is not None:
+                            result.append((neighbor, edge))
+                            visited.add(neighbor_id)
+                            next_frontier.add(neighbor_id)
+            frontier = next_frontier
+
+        return result
+
+    # --- Batch ---
+
+    async def save_nodes_batch(self, nodes: Sequence[Node]) -> None:
+        for node in nodes:
+            self._nodes[node.id] = node
+
+    async def save_edges_batch(self, edges: Sequence[Edge]) -> None:
+        for edge in edges:
+            self._edges[edge.id] = edge
+
+    # --- Maintenance ---
+
+    async def prune_edges(self, *, weight_below: float = 0.1) -> int:
+        to_delete = [eid for eid, e in self._edges.items() if e.weight < weight_below]
+        for eid in to_delete:
+            del self._edges[eid]
+        return len(to_delete)
+
+    async def decay_vitality(self, *, factor: float = 0.95) -> int:
+        count = 0
+        for node in self._nodes.values():
+            node.vitality *= factor
+            count += 1
+        return count
+
+
+def _cosine_similarity(a: list[float], b: list[float]) -> float:
+    if len(a) != len(b) or not a:
+        return 0.0
+    dot = sum(x * y for x, y in zip(a, b, strict=True))
+    norm_a = sum(x * x for x in a) ** 0.5
+    norm_b = sum(x * x for x in b) ** 0.5
+    if norm_a == 0 or norm_b == 0:
+        return 0.0
+    return dot / (norm_a * norm_b)

src/synaptic/backends/postgresql.py

@@ -0,0 +1,19 @@
+"""PostgreSQL backend stub — Phase C (v0.2.0)."""
+
+from __future__ import annotations
+
+
+class PostgreSQLBackend:
+    """PostgreSQL backend with AGE + pgvector + pg_trgm.
+
+    Not yet implemented. Planned for synaptic-memory v0.2.0.
+    See docs for the full PostgreSQL schema.
+    """
+
+    def __init__(self, dsn: str = "") -> None:
+        msg = (
+            "PostgreSQL backend is not yet implemented. "
+            "Use MemoryBackend or SQLiteBackend for now. "
+            "Planned for synaptic-memory v0.2.0."
+        )
+        raise NotImplementedError(msg)