feat: v0.3.0 — 프로토콜 구현체 + LRU 캐시 + JSON export + 노드 병합

extensions/ 모듈 (P4):
- RegexTagExtractor: 15개 기술 도메인 패턴 (한/영), 커스텀 패턴 확장 가능
- LLMQueryRewriter: LLM 기반 쿼리 재작성 (economy tier), StaticQueryRewriter(테스트용)
- MockEmbeddingProvider: 결정적 해시 기반 (테스트용)
- OpenAIEmbeddingProvider: OpenAI/vLLM/Ollama 호환 임베딩 (httpx)

LRU 캐시 (P5):
- NodeCache: OrderedDict 기반 LRU, maxsize 제한, hit_rate 통계
- SynapticGraph.get()에서 자동 캐시 → add/remove/reinforce/decay 시 invalidate

JSON Export + 노드 병합 (P6):
- export_json(): nodes + edges JSON 직렬화
- merge(source, target): 콘텐츠/태그/통계/엣지 합치고 source 삭제
- find_duplicates(): SequenceMatcher로 유사 제목 탐지 (같은 kind만)

121 unit tests + 13 integration tests = 134 total

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.2.0"
+version = "0.3.0"
 description = "Brain-inspired knowledge graph: spreading activation, Hebbian learning, memory consolidation."
 license = "MIT"
 requires-python = ">=3.12"

src/synaptic/cache.py

@@ -0,0 +1,67 @@
+"""LRU cache layer for frequently accessed nodes."""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+
+from synaptic.models import Node
+
+
+class NodeCache:
+    """Bounded LRU cache for nodes. Thread-safe is NOT guaranteed — async-only.
+
+    Usage:
+        cache = NodeCache(maxsize=256)
+        cache.put(node)
+        node = cache.get("node_id")  # None if miss
+        cache.invalidate("node_id")
+    """
+
+    __slots__ = ("_cache", "_hits", "_maxsize", "_misses")
+
+    def __init__(self, maxsize: int = 256) -> None:
+        self._maxsize = maxsize
+        self._cache: OrderedDict[str, Node] = OrderedDict()
+        self._hits = 0
+        self._misses = 0
+
+    def get(self, node_id: str) -> Node | None:
+        if node_id in self._cache:
+            self._cache.move_to_end(node_id)
+            self._hits += 1
+            return self._cache[node_id]
+        self._misses += 1
+        return None
+
+    def put(self, node: Node) -> None:
+        if node.id in self._cache:
+            self._cache.move_to_end(node.id)
+        self._cache[node.id] = node
+        if len(self._cache) > self._maxsize:
+            self._cache.popitem(last=False)
+
+    def invalidate(self, node_id: str) -> None:
+        self._cache.pop(node_id, None)
+
+    def clear(self) -> None:
+        self._cache.clear()
+        self._hits = 0
+        self._misses = 0
+
+    @property
+    def size(self) -> int:
+        return len(self._cache)
+
+    @property
+    def hit_rate(self) -> float:
+        total = self._hits + self._misses
+        return self._hits / total if total > 0 else 0.0
+
+    def stats(self) -> dict[str, int | float]:
+        return {
+            "size": self.size,
+            "maxsize": self._maxsize,
+            "hits": self._hits,
+            "misses": self._misses,
+            "hit_rate": round(self.hit_rate, 3),
+        }

src/synaptic/exporter.py

@@ -1,8 +1,10 @@
-"""Markdown exporter for knowledge graph."""
+"""Exporters for knowledge graph — Markdown and JSON."""
 
 from __future__ import annotations
 
-from synaptic.models import Node
+import json
+
+from synaptic.models import Edge, Node
 from synaptic.protocols import StorageBackend
 
 
@@ -56,3 +58,63 @@ async def export(
                 lines.append(f"\n{node.content}\n")
 
         return "\n".join(lines)
+
+
+class JSONExporter:
+    """Exports nodes and edges as JSON."""
+
+    __slots__ = ()
+
+    async def export(
+        self,
+        backend: StorageBackend,
+        *,
+        node_ids: list[str] | None = None,
+    ) -> str:
+        if node_ids is not None:
+            nodes: list[Node] = []
+            for nid in node_ids:
+                node = await backend.get_node(nid)
+                if node is not None:
+                    nodes.append(node)
+        else:
+            nodes = await backend.list_nodes(limit=500)
+
+        # Collect edges for these nodes
+        node_id_set = {n.id for n in nodes}
+        edges: list[Edge] = []
+        for node in nodes:
+            node_edges = await backend.get_edges(node.id, direction="outgoing")
+            for edge in node_edges:
+                if edge.target_id in node_id_set:
+                    edges.append(edge)
+
+        data = {
+            "nodes": [
+                {
+                    "id": n.id,
+                    "kind": str(n.kind),
+                    "title": n.title,
+                    "content": n.content,
+                    "tags": n.tags,
+                    "level": str(n.level),
+                    "vitality": n.vitality,
+                    "access_count": n.access_count,
+                    "success_count": n.success_count,
+                    "failure_count": n.failure_count,
+                    "source": n.source,
+                }
+                for n in nodes
+            ],
+            "edges": [
+                {
+                    "id": e.id,
+                    "source_id": e.source_id,
+                    "target_id": e.target_id,
+                    "kind": str(e.kind),
+                    "weight": e.weight,
+                }
+                for e in edges
+            ],
+        }
+        return json.dumps(data, ensure_ascii=False, indent=2)

src/synaptic/extensions/__init__.py

@@ -0,0 +1 @@
+"""Synaptic Memory extensions — protocol implementations."""

src/synaptic/extensions/embedder.py

@@ -0,0 +1,77 @@
+"""Embedding providers — generate vector embeddings for nodes."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class EmbeddingProvider(Protocol):
+    """Generate embedding vectors from text."""
+
+    async def embed(self, text: str) -> list[float]: ...
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]: ...
+
+
+class MockEmbeddingProvider:
+    """Mock embedding provider for testing. Returns deterministic vectors."""
+
+    __slots__ = ("_dim",)
+
+    def __init__(self, dim: int = 4) -> None:
+        self._dim = dim
+
+    async def embed(self, text: str) -> list[float]:
+        # Deterministic: hash text into a vector
+        h = hash(text) & 0xFFFFFFFF
+        return [((h >> (i * 8)) & 0xFF) / 255.0 for i in range(self._dim)]
+
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        return [await self.embed(t) for t in texts]
+
+
+class OpenAIEmbeddingProvider:
+    """OpenAI-compatible embedding provider (works with OpenAI, vLLM, Ollama).
+
+    Usage:
+        provider = OpenAIEmbeddingProvider(
+            api_base="https://api.openai.com/v1",
+            api_key="sk-...",
+            model="text-embedding-3-small",
+        )
+    """
+
+    __slots__ = ("_api_base", "_api_key", "_model")
+
+    def __init__(
+        self,
+        api_base: str = "https://api.openai.com/v1",
+        api_key: str = "",
+        model: str = "text-embedding-3-small",
+    ) -> None:
+        self._api_base = api_base.rstrip("/")
+        self._api_key = api_key
+        self._model = model
+
+    async def embed(self, text: str) -> list[float]:
+        results = await self.embed_batch([text])
+        return results[0]
+
+    async def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        import httpx  # type: ignore[import-untyped]  # noqa: PLC0415
+
+        url = f"{self._api_base}/embeddings"
+        headers: dict[str, str] = {"Content-Type": "application/json"}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+
+        payload = {"model": self._model, "input": texts}
+
+        async with httpx.AsyncClient(timeout=60) as client:
+            resp = await client.post(url, headers=headers, json=payload)
+            resp.raise_for_status()
+            data = resp.json()
+
+        embeddings: list[list[float]] = []
+        for item in sorted(data["data"], key=lambda x: x["index"]):  # type: ignore[no-any-return]
+            embeddings.append(item["embedding"])  # type: ignore[index]
+        return embeddings

src/synaptic/extensions/rewriter.py

@@ -0,0 +1,60 @@
+"""LLM-based query rewriter — expands search queries via language model."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class LLMChatFn(Protocol):
+    """Minimal LLM chat interface for query rewriting."""
+
+    async def __call__(self, *, system: str, user: str, max_tokens: int) -> str: ...
+
+
+class LLMQueryRewriter:
+    """Rewrites search queries using an LLM for better recall.
+
+    Generates 2-3 alternative phrasings of the query.
+    Uses economy-tier models (e.g. Haiku) for cost efficiency.
+    """
+
+    __slots__ = ("_chat_fn",)
+
+    def __init__(self, chat_fn: LLMChatFn) -> None:
+        self._chat_fn = chat_fn
+
+    async def rewrite(self, query: str) -> list[str]:
+        """Rewrite query into 2-3 alternative forms."""
+        if not query.strip():
+            return []
+
+        system = (
+            "You are a search query expander. Given a search query, "
+            "generate 2-3 alternative phrasings that could match relevant documents. "
+            "Include both Korean and English variants if applicable. "
+            "Return one query per line, nothing else."
+        )
+        try:
+            response = await self._chat_fn(
+                system=system,
+                user=f"Query: {query}",
+                max_tokens=256,
+            )
+            lines = [
+                line.strip().lstrip("- ·•0123456789.") for line in response.strip().splitlines()
+            ]
+            return [line for line in lines if line and line != query][:3]
+        except Exception:
+            return []
+
+
+class StaticQueryRewriter:
+    """Static query rewriter for testing — returns predefined expansions."""
+
+    __slots__ = ("_expansions",)
+
+    def __init__(self, expansions: dict[str, list[str]] | None = None) -> None:
+        self._expansions = expansions or {}
+
+    async def rewrite(self, query: str) -> list[str]:
+        return self._expansions.get(query, [])

src/synaptic/extensions/tagger_regex.py

@@ -0,0 +1,48 @@
+"""Regex-based tag extractor — zero LLM dependency."""
+
+from __future__ import annotations
+
+import re
+
+_I = re.IGNORECASE
+
+# Common tech/domain terms to extract as tags
+_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    ("api", re.compile(r"\bAPI\b|\bREST\b|\bGraphQL\b|\bgRPC\b", _I)),
+    ("database", re.compile(r"\b(?:DB|database|SQL|PostgreSQL|SQLite|MySQL|MongoDB)\b", _I)),
+    ("deploy", re.compile(r"\b(?:deploy|배포|CI/CD|릴리즈|release)\b", _I)),
+    ("test", re.compile(r"\b(?:test|테스트|검증|QA|unittest|pytest)\b", _I)),
+    ("security", re.compile(r"\b(?:security|보안|auth|인증|취약점|OWASP)\b", _I)),
+    ("performance", re.compile(r"\b(?:performance|성능|latency|throughput|최적화)\b", _I)),
+    ("bug", re.compile(r"\b(?:bug|버그|오류|에러|error|fix|수정)\b", _I)),
+    ("frontend", re.compile(r"\b(?:frontend|프론트|React|Vue|UI|CSS|HTML)\b", _I)),
+    ("backend", re.compile(r"\b(?:backend|백엔드|서버|server|FastAPI|Django)\b", _I)),
+    ("infra", re.compile(r"\b(?:infra|인프라|Docker|K8s|Kubernetes|AWS|GCP)\b", _I)),
+    ("ai", re.compile(r"\b(?:AI|ML|LLM|GPT|Claude|embedding|벡터)\b", _I)),
+    ("docs", re.compile(r"\b(?:doc|문서|README|documentation|문서화)\b", _I)),
+    ("refactor", re.compile(r"\b(?:refactor|리팩토링|개선|cleanup|정리)\b", _I)),
+    ("design", re.compile(r"\b(?:design|설계|architecture|아키텍처|구조)\b", _I)),
+    ("monitoring", re.compile(r"\b(?:monitoring|모니터링|로그|logging|메트릭|alert)\b", _I)),
+]
+
+
+class RegexTagExtractor:
+    """Extract tags from text using regex patterns. Zero dependencies."""
+
+    __slots__ = ("_patterns",)
+
+    def __init__(
+        self,
+        extra_patterns: list[tuple[str, re.Pattern[str]]] | None = None,
+    ) -> None:
+        self._patterns = [*_PATTERNS]
+        if extra_patterns:
+            self._patterns.extend(extra_patterns)
+
+    def extract(self, text: str) -> list[str]:
+        """Extract matching tags from text."""
+        tags: list[str] = []
+        for tag, pattern in self._patterns:
+            if pattern.search(text):
+                tags.append(tag)
+        return tags