genome-memory 1.0.0__py3-none-any.whl

genome/__init__.py

@@ -0,0 +1,75 @@
+"""GENOME: DNA-inspired memory primitives for AI."""
+
+# Copyright 2026 Northtek (FrostByte Digital LLC)
+# SPDX-License-Identifier: Apache-2.0
+
+__version__ = "1.0.0"
+
+
+_RELATION_CONSTANTS = {"SUPERSEDES", "CONTRADICTS", "DERIVED_FROM", "RELATES_TO", "CAUSES"}
+
+
+_OBSERVABILITY_EXPORTS = {
+    "ErrorCapture", "CapturedError", "get_error_capture",
+    "MetricsRegistry", "get_metrics", "configure_logging", "get_logger",
+}
+
+_CONFLICT_EXPORTS = {"ConflictResolver", "ConflictDecision"}
+
+
+def __getattr__(name: str):
+    # Lazy imports to avoid loading heavy deps (torch, sentence-transformers) on
+    # every `import genome`. The user pays for what they use.
+    if name == "Memory":
+        from genome.memory import Memory
+        return Memory
+    if name == "AsyncMemory":
+        from genome.memory import AsyncMemory
+        return AsyncMemory
+    if name == "MemoryRecord":
+        from genome.memory import MemoryRecord
+        return MemoryRecord
+    if name == "SearchResult":
+        from genome.memory import SearchResult
+        return SearchResult
+    if name == "MemoryEdge":
+        from genome.memory import MemoryEdge
+        return MemoryEdge
+    if name == "EmbeddingProvider":
+        from genome.embeddings import EmbeddingProvider
+        return EmbeddingProvider
+    if name in _RELATION_CONSTANTS:
+        from genome.memory import graph as _graph
+        return getattr(_graph, name)
+    if name in _OBSERVABILITY_EXPORTS:
+        from genome import observability as _obs
+        return getattr(_obs, name)
+    if name in _CONFLICT_EXPORTS:
+        from genome.memory import conflict as _conflict
+        return getattr(_conflict, name)
+    raise AttributeError(f"module 'genome' has no attribute {name!r}")
+
+
+__all__ = [
+    "Memory",
+    "AsyncMemory",
+    "MemoryRecord",
+    "SearchResult",
+    "MemoryEdge",
+    "EmbeddingProvider",
+    "SUPERSEDES",
+    "CONTRADICTS",
+    "DERIVED_FROM",
+    "RELATES_TO",
+    "CAUSES",
+    "ErrorCapture",
+    "CapturedError",
+    "get_error_capture",
+    "MetricsRegistry",
+    "get_metrics",
+    "configure_logging",
+    "get_logger",
+    "ConflictResolver",
+    "ConflictDecision",
+    "__version__",
+]

genome/adapters/__init__.py

@@ -0,0 +1,10 @@
+"""Framework adapters for genome.
+
+Each adapter is soft-optional: importing `genome.adapters.langchain` only fails
+if the user tries to use it without langchain installed. Core genome has zero
+framework dependencies.
+"""
+
+# Copyright 2026 Northtek (FrostByte Digital LLC)
+# SPDX-License-Identifier: Apache-2.0
+

genome/adapters/langchain.py

@@ -0,0 +1,188 @@
+"""LangChain adapter.
+
+Two classes exposed:
+
+1. `GenomeChatMessageHistory` -- implements `BaseChatMessageHistory`. Persists
+   conversation turns as memories in a genome store, scoped by `session_id`.
+   Drop-in replacement for `ChatMessageHistory` / `FileChatMessageHistory`.
+
+2. `GenomeRetrieverMemory` -- implements `BaseMemory` for retrieval-augmented
+   chat. Calls `Memory.search` to surface relevant historical memories for the
+   current prompt. Use this in LangChain chains that want semantic recall.
+
+Install: `pip install langchain-core` (genome does not depend on it).
+"""
+
+# Copyright 2026 Northtek (FrostByte Digital LLC)
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from genome.memory.facade import Memory
+
+if TYPE_CHECKING:
+    # Only imported for type checking; runtime import happens lazily below.
+    from langchain_core.messages import BaseMessage
+
+
+def _require_langchain():
+    try:
+        from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
+    except ImportError as e:
+        raise ImportError(
+            "langchain adapter requires langchain-core. "
+            "Install with: pip install langchain-core"
+        ) from e
+    return AIMessage, HumanMessage, BaseMessage
+
+
+class GenomeChatMessageHistory:
+    """A BaseChatMessageHistory backed by a genome Memory store.
+
+    Each message (human or AI) becomes a memory. The session_id scopes them via
+    user_id, so multiple concurrent conversations stay isolated.
+
+    Usage::
+
+        from genome import Memory
+        from genome.adapters.langchain import GenomeChatMessageHistory
+
+        mem = Memory(storage="chat.db")
+        history = GenomeChatMessageHistory(memory=mem, session_id="session_123")
+        # Use as a normal LangChain BaseChatMessageHistory
+    """
+
+    def __init__(self, memory: Memory, session_id: str) -> None:
+        _require_langchain()  # will raise if not installed
+        self.memory = memory
+        self.session_id = session_id
+
+    @property
+    def messages(self) -> list[BaseMessage]:
+        from langchain_core.messages import AIMessage, HumanMessage
+        records = self.memory.list_all(user_id=self.session_id)
+        records.sort(key=lambda r: r.created_at)
+        out: list[BaseMessage] = []
+        for r in records:
+            role = r.metadata.get("role", "human")
+            if role == "ai":
+                out.append(AIMessage(content=r.content))
+            else:
+                out.append(HumanMessage(content=r.content))
+        return out
+
+    def add_message(self, message: BaseMessage) -> None:
+        role = "ai" if message.__class__.__name__ == "AIMessage" else "human"
+        self.memory.add(
+            str(message.content),
+            user_id=self.session_id,
+            metadata={"role": role, "source": "chat"},
+        )
+
+    def add_messages(self, messages) -> None:
+        """Bulk add. Part of the current BaseChatMessageHistory contract --
+        RunnableWithMessageHistory calls this rather than add_message."""
+        for m in messages:
+            self.add_message(m)
+
+    def add_user_message(self, message: str) -> None:
+        self.memory.add(
+            message,
+            user_id=self.session_id,
+            metadata={"role": "human", "source": "chat"},
+        )
+
+    def add_ai_message(self, message: str) -> None:
+        self.memory.add(
+            message,
+            user_id=self.session_id,
+            metadata={"role": "ai", "source": "chat"},
+        )
+
+    def clear(self) -> None:
+        self.memory.reset(user_id=self.session_id)
+
+
+class GenomeRetrieverMemory:
+    """A BaseMemory-compatible class that injects relevant historical memories
+    into the chain's variables on each call.
+
+    Usage::
+
+        from genome import Memory
+        from genome.adapters.langchain import GenomeRetrieverMemory
+        from langchain_core.prompts import ChatPromptTemplate
+
+        mem = Memory(storage="chat.db")
+        retriever = GenomeRetrieverMemory(
+            memory=mem, user_id="alice", memory_key="history", top_k=5,
+        )
+        prompt = ChatPromptTemplate.from_messages([
+            ("system", "Relevant memories:\\n{history}"),
+            ("user", "{input}"),
+        ])
+        chain = prompt | llm
+        chain.invoke({"input": "what do I like?", **retriever.load_memory_variables({"input": "what do I like?"})})
+    """
+
+    def __init__(
+        self,
+        memory: Memory,
+        *,
+        user_id: str,
+        memory_key: str = "history",
+        input_key: str = "input",
+        top_k: int = 5,
+        agent_id: str | None = None,
+    ) -> None:
+        _require_langchain()
+        self.memory = memory
+        self.user_id = user_id
+        self.memory_key = memory_key
+        self.input_key = input_key
+        self.top_k = top_k
+        self.agent_id = agent_id
+
+    @property
+    def memory_variables(self) -> list[str]:
+        return [self.memory_key]
+
+    def load_memory_variables(self, inputs: dict[str, Any]) -> dict[str, str]:
+        query = inputs.get(self.input_key) or inputs.get("query") or ""
+        if not query:
+            return {self.memory_key: ""}
+        results = self.memory.search(
+            str(query),
+            user_id=self.user_id,
+            agent_id=self.agent_id,
+            limit=self.top_k,
+        )
+        lines = [f"- {r.content}" for r in results]
+        return {self.memory_key: "\n".join(lines) if lines else "(no relevant memories)"}
+
+    def save_context(self, inputs: dict[str, Any], outputs: dict[str, Any]) -> None:
+        """Persist the turn. Both the user input and AI output become memories."""
+        user_text = str(inputs.get(self.input_key, "") or "")
+        ai_text = str(outputs.get("output", "") or outputs.get("response", "") or "")
+        if user_text:
+            self.memory.add(
+                user_text,
+                user_id=self.user_id,
+                agent_id=self.agent_id,
+                metadata={"role": "human", "source": "chat"},
+            )
+        if ai_text:
+            self.memory.add(
+                ai_text,
+                user_id=self.user_id,
+                agent_id=self.agent_id,
+                metadata={"role": "ai", "source": "chat"},
+            )
+
+    def clear(self) -> None:
+        self.memory.reset(user_id=self.user_id, agent_id=self.agent_id)
+
+
+__all__ = ["GenomeChatMessageHistory", "GenomeRetrieverMemory"]

genome/adapters/llamaindex.py

@@ -0,0 +1,133 @@
+"""LlamaIndex adapter.
+
+Exposes `GenomeChatMemory`, a BaseMemory-compatible class for LlamaIndex
+agents/engines that delegates storage + retrieval to genome.
+
+Install: `pip install llama-index-core` (genome does not depend on it).
+"""
+
+# Copyright 2026 Northtek (FrostByte Digital LLC)
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Any
+
+from genome.memory.facade import Memory
+
+
+def _require_llamaindex():
+    try:
+        from llama_index.core.llms import ChatMessage
+    except ImportError as e:
+        raise ImportError(
+            "llamaindex adapter requires llama-index-core. "
+            "Install with: pip install llama-index-core"
+        ) from e
+    return ChatMessage
+
+
+class GenomeChatMemory:
+    """A minimal LlamaIndex-compatible ChatMemory backed by genome.
+
+    Stores each turn as a memory with role metadata. On retrieval, returns the
+    ordered sequence via `get()`, or the top-k semantically relevant via
+    `get_relevant(query)`.
+
+    Usage::
+
+        from genome import Memory
+        from genome.adapters.llamaindex import GenomeChatMemory
+        from llama_index.core.llms import ChatMessage, MessageRole
+
+        mem = Memory(storage="agent.db")
+        chat_memory = GenomeChatMemory(memory=mem, session_id="session_1")
+        chat_memory.put(ChatMessage(role=MessageRole.USER, content="hello"))
+        messages = chat_memory.get()  # ordered history
+        relevant = chat_memory.get_relevant("what did I say about coffee?", top_k=3)
+    """
+
+    def __init__(
+        self,
+        memory: Memory,
+        *,
+        session_id: str,
+        token_limit: int | None = None,
+    ) -> None:
+        _require_llamaindex()
+        self.memory = memory
+        self.session_id = session_id
+        self.token_limit = token_limit
+
+    def put(self, message: Any) -> None:
+        """Add a ChatMessage to memory."""
+        role = str(getattr(getattr(message, "role", None), "value", message.role)).lower()
+        content = str(message.content)
+        self.memory.add(
+            content,
+            user_id=self.session_id,
+            metadata={"role": role, "source": "chat"},
+        )
+
+    def set(self, messages: list[Any]) -> None:
+        """Replace all messages in this session."""
+        self.memory.reset(user_id=self.session_id)
+        for m in messages:
+            self.put(m)
+
+    def get(self, input: str | None = None, **kwargs: Any) -> list[Any]:
+        """Return the full chronological message history for this session.
+
+        Accepts LlamaIndex's `get(input=..., **kwargs)` call signature (the
+        agent runtime passes the current user message as `input`) so this
+        object is drop-in usable there. `input` is accepted for compatibility;
+        chronological history is returned regardless -- use `get_relevant()`
+        for retrieval-aware recall.
+        """
+        from llama_index.core.llms import ChatMessage, MessageRole
+        records = self.memory.list_all(user_id=self.session_id)
+        records.sort(key=lambda r: r.created_at)
+        out: list[ChatMessage] = []
+        for r in records:
+            role_str = r.metadata.get("role", "user").lower()
+            role = {
+                "user": MessageRole.USER,
+                "human": MessageRole.USER,
+                "ai": MessageRole.ASSISTANT,
+                "assistant": MessageRole.ASSISTANT,
+                "system": MessageRole.SYSTEM,
+            }.get(role_str, MessageRole.USER)
+            out.append(ChatMessage(role=role, content=r.content))
+        return out
+
+    def get_all(self, **kwargs: Any) -> list[Any]:
+        """Alias for get() -- matches LlamaIndex BaseMemory naming."""
+        return self.get()
+
+    def get_relevant(self, query: str, top_k: int = 5) -> list[Any]:
+        """Return the top-k semantically relevant historical messages for the query.
+
+        genome-specific: this is the recall-style retrieval that matters for
+        long-running agents whose full history exceeds the context window.
+        """
+        from llama_index.core.llms import ChatMessage, MessageRole
+        results = self.memory.search(query, user_id=self.session_id, limit=top_k)
+        out: list[ChatMessage] = []
+        for r in results:
+            role_str = r.record.metadata.get("role", "user").lower()
+            role = {
+                "user": MessageRole.USER,
+                "human": MessageRole.USER,
+                "ai": MessageRole.ASSISTANT,
+                "assistant": MessageRole.ASSISTANT,
+                "system": MessageRole.SYSTEM,
+            }.get(role_str, MessageRole.USER)
+            out.append(ChatMessage(role=role, content=r.content))
+        return out
+
+    def reset(self) -> None:
+        """Clear this session's history."""
+        self.memory.reset(user_id=self.session_id)
+
+
+__all__ = ["GenomeChatMemory"]

genome/agent/__init__.py

@@ -0,0 +1,41 @@
+"""Agent runtime for genome.
+
+Letta-style hierarchical memory (core + archival) with tool-callable
+interfaces. Works with any LLM SDK (Anthropic, OpenAI, any tool-calling
+model) by exposing tool schemas the agent can invoke.
+
+Usage::
+
+    from genome import Memory
+    from genome.agent import AgentMemory, tool_schemas
+
+    mem = Memory(storage="agent.db")
+    agent_mem = AgentMemory(memory=mem, user_id="alice", session_id="s1")
+
+    # Render the core memory block into your system prompt
+    system_prompt = f"You are a helpful assistant.\\n\\n{agent_mem.render_core()}"
+
+    # Advertise the memory tools to your LLM
+    tools = tool_schemas()  # Anthropic format
+
+    # When the LLM calls a tool:
+    result = agent_mem.handle_tool_call(tool_name, tool_args)
+"""
+
+# Copyright 2026 Northtek (FrostByte Digital LLC)
+# SPDX-License-Identifier: Apache-2.0
+
+from genome.agent.memory import AgentMemory, CoreBlock
+from genome.agent.tools import (
+    ANTHROPIC_TOOL_SCHEMAS,
+    OPENAI_TOOL_SCHEMAS,
+    tool_schemas,
+)
+
+__all__ = [
+    "AgentMemory",
+    "CoreBlock",
+    "tool_schemas",
+    "ANTHROPIC_TOOL_SCHEMAS",
+    "OPENAI_TOOL_SCHEMAS",
+]