dory-memory 0.3.0__py3-none-any.whl

dory/__init__.py

@@ -0,0 +1,13 @@
+from .graph import Graph
+from .schema import NodeType, EdgeType
+from .memory import DoryMemory
+from . import session, activation, consolidation
+from .pipeline import Observer, Prefixer, PrefixResult, Decayer, DecayConfig, Reflector
+
+__all__ = [
+    "DoryMemory",
+    "Graph", "NodeType", "EdgeType",
+    "session", "activation", "consolidation",
+    "Observer", "Prefixer", "PrefixResult",
+    "Decayer", "DecayConfig", "Reflector",
+]

dory/activation.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from .graph import Graph
+from .schema import now_iso, EdgeType
+
+
+def _fmt_date(iso: str | None) -> str:
+    """Return 'YYYY-MM-DD' from an ISO timestamp, or '' on failure."""
+    if not iso:
+        return ""
+    try:
+        dt = datetime.fromisoformat(iso.replace("Z", "+00:00"))
+        return dt.strftime("%Y-%m-%d")
+    except Exception:
+        return ""
+
+
+_STOPWORDS = frozenset({
+    "a", "an", "the", "is", "are", "was", "were", "be", "been", "have", "has",
+    "had", "do", "does", "did", "will", "would", "should", "may", "might",
+    "can", "could", "to", "of", "in", "on", "at", "for", "with", "by", "from",
+    "as", "and", "or", "but", "not", "this", "that", "it", "its", "also",
+    "more", "than", "just", "very", "all", "any", "one", "two", "get",
+    "use", "uses", "used", "using", "new", "add", "i", "my", "me", "you",
+    "your", "we", "our", "what", "which", "who", "when", "where", "how",
+    "first", "last", "did", "after", "before", "about",
+})
+
+
+def _fts_query(text: str, n: int = 10) -> str:
+    """
+    Extract meaningful terms from text for FTS5, joined with OR.
+    OR mode gives much better recall than FTS5's default AND.
+    Includes numeric tokens (years, day numbers) for date matching.
+    """
+    import re
+    # Alpha tokens (words)
+    alpha = re.findall(r"[a-zA-Z]\w*", text)
+    # Numeric tokens: extract raw digit sequences (1-4 digits) — captures years, day
+    # numbers, and ordinals like "15th" (extracts "15"). Longer numbers are ignored.
+    numeric = [m for m in re.findall(r"\d+", text) if 1 <= len(m) <= 4]
+
+    seen: set[str] = set()
+    terms = []
+
+    for w in alpha:
+        lo = w.lower()
+        if len(lo) >= 3 and lo not in _STOPWORDS and lo not in seen:
+            seen.add(lo)
+            terms.append(lo)
+            if len(terms) >= n:
+                break
+
+    for num in numeric:
+        if num not in seen:
+            seen.add(num)
+            terms.append(num)
+
+    return " OR ".join(terms) if terms else text
+
+
+def find_seeds(query: str, graph: Graph) -> list[str]:
+    """
+    Return node IDs ranked by relevance to the query.
+
+    Priority order:
+      1. FTS5 BM25 search (best recall, handles partial terms)
+      2. Vector KNN search (semantic similarity, if Ollama running)
+      3. Substring fallback (always works, no dependencies)
+
+    Results are deduplicated and merged, with FTS hits ranked first.
+    """
+    from . import store, vector
+
+    seen: dict[str, int] = {}  # node_id → score (lower = better rank)
+
+    # 1. FTS BM25 — use OR over key terms for recall (avoids AND-mode over-constraining)
+    fts_ids = store.search_fts(_fts_query(query), graph.path)
+    for rank, nid in enumerate(fts_ids):
+        if nid in graph._nodes:
+            seen[nid] = rank
+
+    # 2. Vector KNN (if available)
+    if vector.available():
+        vec_ids = vector.knn_search(query, graph.path)
+        for rank, nid in enumerate(vec_ids):
+            if nid in graph._nodes and nid not in seen:
+                seen[nid] = len(fts_ids) + rank
+
+    # 3. Substring fallback for anything not caught above
+    if not seen:
+        terms = query.lower().split()
+        for node in graph.all_nodes():
+            text = (node.content + " " + " ".join(node.tags)).lower()
+            hits = sum(1 for t in terms if t in text)
+            if hits:
+                seen[node.id] = -hits  # negative so higher hits = lower score
+
+    return sorted(seen, key=lambda nid: seen[nid])
+
+
+def spread(
+    seed_ids: list[str],
+    graph: Graph,
+    depth: int = 3,
+    depth_decay: float = 0.5,
+    threshold: float = 0.05,
+) -> dict[str, float]:
+    """
+    Spread activation from seed nodes outward through the graph.
+    Returns {node_id: activation_level} for all nodes above threshold.
+    Activation received = source_activation × edge_weight × depth_decay per hop.
+    """
+    activation: dict[str, float] = {sid: 1.0 for sid in seed_ids}
+    frontier: dict[str, float] = dict(activation)
+
+    traversed_edges: set[str] = set()
+
+    for _ in range(depth):
+        next_frontier: dict[str, float] = {}
+        for node_id, level in frontier.items():
+            for edge in graph.edges_for_node(node_id):
+                neighbor_id = (
+                    edge.target_id if edge.source_id == node_id else edge.source_id
+                )
+                received = level * edge.weight * depth_decay
+                if received >= threshold:
+                    traversed_edges.add(edge.id)
+                    current = activation.get(neighbor_id, 0.0)
+                    new_val = min(1.0, current + received)
+                    if new_val > current:
+                        activation[neighbor_id] = new_val
+                        next_frontier[neighbor_id] = new_val
+        frontier = next_frontier
+        if not frontier:
+            break
+
+    # Record activation on touched nodes and traversed edges
+    now = now_iso()
+    for node_id, level in activation.items():
+        if level >= threshold:
+            node = graph.get_node(node_id)
+            if node:
+                node.activation_count += 1
+                node.last_activated = now
+
+    for edge in graph.all_edges():
+        if edge.id in traversed_edges:
+            edge.activation_count += 1
+            edge.last_activated = now
+
+    return {nid: v for nid, v in activation.items() if v >= threshold}
+
+
+def serialize(activated: dict[str, float], graph: Graph, max_nodes: int = 20) -> str:
+    """Convert activated subgraph to a natural language context block."""
+    if not activated:
+        return "(no relevant memories found)"
+
+    ranked = sorted(
+        activated.items(),
+        key=lambda kv: (
+            kv[1],
+            graph.get_node(kv[0]).salience if graph.get_node(kv[0]) else 0,
+        ),
+        reverse=True,
+    )[:max_nodes]
+
+    lines = []
+    for node_id, level in ranked:
+        node = graph.get_node(node_id)
+        if not node:
+            continue
+        core_marker = " [CORE]" if node.is_core else ""
+        # SESSION nodes already embed the date in their content as "[YYYY-MM-DD] Session: ..."
+        # so we don't add a redundant (and potentially wrong) date hint for them.
+        # EVENT nodes still get the hint from created_at.
+        date_hint = ""
+        if node.type.value == "EVENT" and node.created_at:
+            d = _fmt_date(node.created_at)
+            if d:
+                date_hint = f" ({d})"
+        lines.append(f"- [{node.type.value}{core_marker}]{date_hint} {node.content}")
+
+    # Include edges between activated nodes
+    activated_ids = set(activated)
+    edge_lines = []
+    seen: set[tuple] = set()
+    for edge in graph.all_edges():
+        if edge.source_id in activated_ids and edge.target_id in activated_ids:
+            key = (edge.source_id, edge.target_id, edge.type.value)
+            if key not in seen:
+                src = graph.get_node(edge.source_id)
+                tgt = graph.get_node(edge.target_id)
+                if src and tgt:
+                    if edge.type == EdgeType.SUPERSEDES:
+                        date = _fmt_date(src.superseded_at or edge.created_at)
+                        date_str = f" (updated {date})" if date else ""
+                        edge_lines.append(
+                            f"  [KNOWLEDGE UPDATE{date_str}] Previously: {src.content} → Now: {tgt.content}"
+                        )
+                    else:
+                        edge_lines.append(
+                            f"  {src.content} --[{edge.type.value}]--> {tgt.content}"
+                        )
+                    seen.add(key)
+
+    result = "Activated memories:\n" + "\n".join(lines)
+    if edge_lines:
+        result += "\n\nRelationships:\n" + "\n".join(edge_lines[:15])
+    return result

dory/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""
+Dory framework adapters.
+
+from dory.adapters.langchain import DoryMemoryAdapter   # LangChain BaseMemory
+from dory.adapters.langgraph import DoryMemoryNode      # LangGraph node functions
+from dory.adapters.multi_agent import SharedMemoryPool  # thread-safe multi-agent memory
+"""

dory/adapters/langchain.py

@@ -0,0 +1,156 @@
+"""
+LangChain memory adapter for Dory.
+
+Implements LangChain's BaseMemory interface so Dory can be used as a
+drop-in memory backend in any LangChain chain or agent.
+
+Usage:
+    from dory.adapters.langchain import DoryMemoryAdapter
+    from langchain.chains import ConversationChain
+    from langchain_anthropic import ChatAnthropic
+
+    memory = DoryMemoryAdapter(
+        db_path="myapp.db",
+        extract_model="claude-haiku-4-5-20251001",
+        extract_backend="anthropic",
+        extract_api_key="sk-ant-...",
+    )
+
+    chain = ConversationChain(
+        llm=ChatAnthropic(model="claude-sonnet-4-6"),
+        memory=memory,
+    )
+
+    response = chain.invoke({"input": "What are we working on?"})
+    # memory context is injected automatically via load_memory_variables()
+    # turns are saved automatically via save_context()
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..memory import DoryMemory
+from .. import store as _store
+
+
+class DoryMemoryAdapter:
+    """
+    LangChain-compatible memory backend backed by Dory.
+
+    Exposes two memory variables:
+      - ``context``  — spreading-activation retrieval from the graph
+      - ``history``  — last N raw turns from the episodic store
+
+    Compatible with langchain BaseMemory duck-typing without requiring
+    langchain as a hard dependency.
+    """
+
+    memory_variables: list[str] = ["context", "history"]
+
+    def __init__(
+        self,
+        db_path: str | Path | None = None,
+        extract_model: str | None = None,
+        extract_backend: str = "ollama",
+        extract_base_url: str = "http://localhost:11434",
+        extract_api_key: str = "local",
+        history_turns: int = 6,
+        input_key: str = "input",
+        output_key: str = "output",
+    ) -> None:
+        self._dory = DoryMemory(
+            db_path=db_path,
+            extract_model=extract_model,
+            extract_backend=extract_backend,
+            extract_base_url=extract_base_url,
+            extract_api_key=extract_api_key,
+        )
+        self._history_turns = history_turns
+        self._input_key = input_key
+        self._output_key = output_key
+
+    # ------------------------------------------------------------------
+    # LangChain BaseMemory interface
+    # ------------------------------------------------------------------
+
+    def load_memory_variables(self, inputs: dict[str, Any]) -> dict[str, str]:
+        """
+        Called at the start of each chain run.
+        Retrieves memory context relevant to the current input.
+        """
+        query = inputs.get(self._input_key, "")
+        result = self._dory.build_context(query)
+        return {
+            "context": result.full,
+            "history": self._recent_history(),
+        }
+
+    def save_context(
+        self,
+        inputs: dict[str, Any],
+        outputs: dict[str, Any],
+    ) -> None:
+        """Called at the end of each chain run. Logs both turns."""
+        user_msg = str(inputs.get(self._input_key, ""))
+        ai_msg = str(outputs.get(self._output_key, ""))
+        if user_msg:
+            self._dory.add_turn("user", user_msg)
+        if ai_msg:
+            self._dory.add_turn("assistant", ai_msg)
+
+    def clear(self) -> None:
+        """Flush memory and run consolidation."""
+        self._dory.flush()
+
+    # ------------------------------------------------------------------
+    # Async interface
+    # ------------------------------------------------------------------
+
+    async def aload_memory_variables(
+        self, inputs: dict[str, Any]
+    ) -> dict[str, str]:
+        """Async version of load_memory_variables() for use with async chains."""
+        query = inputs.get(self._input_key, "")
+        result = await self._dory.abuild_context(query)
+        return {
+            "context": result.full,
+            "history": self._recent_history(),
+        }
+
+    async def asave_context(
+        self,
+        inputs: dict[str, Any],
+        outputs: dict[str, Any],
+    ) -> None:
+        """Async version of save_context()."""
+        user_msg = str(inputs.get(self._input_key, ""))
+        ai_msg = str(outputs.get(self._output_key, ""))
+        if user_msg:
+            await self._dory.aadd_turn("user", user_msg)
+        if ai_msg:
+            await self._dory.aadd_turn("assistant", ai_msg)
+
+    async def aclear(self) -> None:
+        """Async flush."""
+        await self._dory.aflush()
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _recent_history(self) -> str:
+        obs = _store.get_observations(
+            self._dory.graph.path,
+            limit=self._history_turns,
+        )
+        if not obs:
+            return ""
+        return "\n".join(
+            f"{o['role'].upper()}: {o['content']}" for o in reversed(obs)
+        )
+
+    # Expose underlying DoryMemory for power users
+    @property
+    def dory(self) -> DoryMemory:
+        return self._dory

dory/adapters/langgraph.py

@@ -0,0 +1,174 @@
+"""
+LangGraph memory adapter for Dory.
+
+Provides DoryMemoryNode — a class whose methods are designed to be used
+as nodes in a LangGraph StateGraph. Handles memory retrieval, turn logging,
+and end-of-session consolidation as discrete graph nodes.
+
+Usage:
+    from dory.adapters.langgraph import DoryMemoryNode, MemoryState
+    from langgraph.graph import StateGraph, START, END
+
+    mem = DoryMemoryNode(
+        db_path="myapp.db",
+        extract_model="claude-haiku-4-5-20251001",
+        extract_backend="anthropic",
+        extract_api_key="sk-ant-...",
+    )
+
+    builder = StateGraph(MemoryState)
+    builder.add_node("load_memory", mem.load_context)
+    builder.add_node("record_turn", mem.record_turn)
+    builder.add_edge(START, "load_memory")
+    builder.add_edge("load_memory", "record_turn")
+    builder.add_edge("record_turn", END)
+    graph = builder.compile()
+
+    # In your agent loop:
+    state = graph.invoke({"query": "What are we building?", "messages": []})
+    # state["context"] is now populated with relevant memory
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, TypedDict
+
+from ..memory import DoryMemory
+
+
+class MemoryState(TypedDict, total=False):
+    """
+    Typed state dict for LangGraph graphs that use DoryMemoryNode.
+
+    Add these fields to your own StateGraph state to enable memory.
+    """
+    query: str                  # the current user query
+    context: str                # memory context retrieved by load_context
+    messages: list[dict]        # conversation messages [{"role": ..., "content": ...}]
+    memory_stats: dict          # populated by consolidate()
+
+
+class DoryMemoryNode:
+    """
+    LangGraph node class for Dory memory operations.
+
+    Each public method has the signature ``(state: dict) -> dict``
+    so it can be passed directly to ``StateGraph.add_node()``.
+    """
+
+    def __init__(
+        self,
+        db_path: str | Path | None = None,
+        extract_model: str | None = None,
+        extract_backend: str = "ollama",
+        extract_base_url: str = "http://localhost:11434",
+        extract_api_key: str = "local",
+    ) -> None:
+        self._dory = DoryMemory(
+            db_path=db_path,
+            extract_model=extract_model,
+            extract_backend=extract_backend,
+            extract_base_url=extract_base_url,
+            extract_api_key=extract_api_key,
+        )
+
+    # ------------------------------------------------------------------
+    # Node functions (state → state)
+    # ------------------------------------------------------------------
+
+    def load_context(self, state: dict[str, Any]) -> dict[str, Any]:
+        """
+        Retrieve memory context relevant to the current query.
+        Populates state["context"] with the result.
+        Add this as the first node in your graph.
+        """
+        query = state.get("query", "")
+        result = self._dory.build_context(query)
+        return {**state, "context": result.full}
+
+    def record_turn(self, state: dict[str, Any]) -> dict[str, Any]:
+        """
+        Log the most recent message to the episodic store.
+        Reads from state["messages"] — expects the last entry to be the
+        turn to record. No-op if messages is empty or no extract_model set.
+        """
+        messages = state.get("messages", [])
+        if messages:
+            last = messages[-1]
+            role = last.get("role", "user")
+            content = last.get("content", "")
+            if content:
+                self._dory.add_turn(role, str(content))
+        return state
+
+    def record_exchange(self, state: dict[str, Any]) -> dict[str, Any]:
+        """
+        Log the last user+assistant exchange (last two messages).
+        Use instead of record_turn when your graph appends both turns at once.
+        """
+        messages = state.get("messages", [])
+        for msg in messages[-2:]:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+            if content:
+                self._dory.add_turn(role, str(content))
+        return state
+
+    def consolidate(self, state: dict[str, Any]) -> dict[str, Any]:
+        """
+        End-of-session consolidation: flush pending turns, run decay/dedup.
+        Populates state["memory_stats"] with consolidation results.
+        Add this as a terminal node or call at session end.
+        """
+        stats = self._dory.flush()
+        return {**state, "memory_stats": stats}
+
+    # ------------------------------------------------------------------
+    # Async node functions
+    # Same signatures as sync versions — use these when your LangGraph
+    # graph is compiled with async support (graph.ainvoke / astream).
+    # ------------------------------------------------------------------
+
+    async def aload_context(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Async version of load_context()."""
+        query = state.get("query", "")
+        result = await self._dory.abuild_context(query)
+        return {**state, "context": result.full}
+
+    async def arecord_turn(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Async version of record_turn()."""
+        messages = state.get("messages", [])
+        if messages:
+            last = messages[-1]
+            role = last.get("role", "user")
+            content = last.get("content", "")
+            if content:
+                await self._dory.aadd_turn(role, str(content))
+        return state
+
+    async def arecord_exchange(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Async version of record_exchange()."""
+        messages = state.get("messages", [])
+        for msg in messages[-2:]:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+            if content:
+                await self._dory.aadd_turn(role, str(content))
+        return state
+
+    async def aconsolidate(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Async version of consolidate()."""
+        stats = await self._dory.aflush()
+        return {**state, "memory_stats": stats}
+
+    # ------------------------------------------------------------------
+    # Direct access
+    # ------------------------------------------------------------------
+
+    @property
+    def dory(self) -> DoryMemory:
+        return self._dory
+
+    def observe(self, content: str, node_type: str = "CONCEPT") -> str:
+        """Manually add a memory node. Returns the new node ID."""
+        return self._dory.observe(content, node_type=node_type)