cortex-vault 0.1.0__py3-none-any.whl

cortex_memory/__init__.py

@@ -0,0 +1,33 @@
+"""
+cortex_memory
+~~~~~~~~~~~~~
+An LLM-powered memory layer backed by a Neo4j knowledge graph.
+
+Public API::
+
+    from cortex_memory import CortexMemory, CortexConfig
+
+    # Quickstart — reads NEO4J_* and GROQ_API_KEY from .env
+    memory = CortexMemory.from_env()
+    response = memory.chat("What do I know about Japan?")
+    memory.ingest("User is planning a trip to Kyoto in October.")
+    memory.close()
+
+Low-level access::
+
+    from cortex_memory import WeightedMemoryRetriever, ingest_text_to_memory_graph
+"""
+
+from cortex_memory.agent import CortexMemory
+from cortex_memory.config import CortexConfig
+from cortex_memory.ingestion.ingestor import ingest_text_to_memory_graph
+from cortex_memory.retrieval.retriever import WeightedMemoryRetriever
+
+__all__ = [
+    "CortexMemory",
+    "CortexConfig",
+    "ingest_text_to_memory_graph",
+    "WeightedMemoryRetriever",
+]
+
+__version__ = "0.1.0"

cortex_memory/__main__.py

@@ -0,0 +1,65 @@
+"""
+cortex_memory.__main__
+~~~~~~~~~~~~~~~~~~~~~~~
+CLI entrypoint — invoked via ``python -m cortex_memory`` or the
+``cortex-memory`` script installed by pyproject.toml.
+
+Usage
+-----
+    cortex-memory chat "What do I know about Japan?"
+    cortex-memory ingest "User loves hiking in the Alps."
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from cortex_memory import CortexMemory
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="cortex-vault",
+        description="Cortex Vault CLI — interact with your Neo4j memory graph.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # --- chat ---
+    chat_parser = sub.add_parser("chat", help="Query the memory agent.")
+    chat_parser.add_argument("query", help="The query to send to the assistant.")
+    chat_parser.add_argument(
+        "--top-k", type=int, default=None, help="Number of memories to retrieve."
+    )
+    chat_parser.add_argument(
+        "--no-ingest", action="store_true", help="Disable auto-ingestion of the query."
+    )
+
+    # --- ingest ---
+    ingest_parser = sub.add_parser("ingest", help="Ingest text into memory.")
+    ingest_parser.add_argument("text", help="Text to evaluate and store.")
+    ingest_parser.add_argument(
+        "--source", default="cli", help="Source tag for the memory (default: 'cli')."
+    )
+
+    args = parser.parse_args()
+
+    with CortexMemory.from_env() as memory:
+        if args.command == "chat":
+            response = memory.chat(
+                args.query,
+                top_k=args.top_k,
+                auto_ingest=not args.no_ingest,
+            )
+            print(f"\n🤖 Assistant:\n{response}\n")
+
+        elif args.command == "ingest":
+            ingested = memory.ingest(args.text, source=args.source)
+            if ingested:
+                print("✅ Memory ingested successfully.")
+            else:
+                print("❌ No ingestion was performed.")
+
+
+if __name__ == "__main__":
+    main()

cortex_memory/agent.py

@@ -0,0 +1,225 @@
+"""
+cortex_memory.agent
+~~~~~~~~~~~~~~~~~~~~
+``CortexMemory`` — the single public class that orchestrates the full
+retrieval-augmented memory pipeline.
+
+Typical usage::
+
+    from cortex_memory import CortexMemory
+
+    memory = CortexMemory.from_env()
+    response = memory.chat("What do I know about my Japan trip?")
+    memory.ingest("User booked flights to Tokyo for next March.")
+    memory.close()
+
+Or as a context manager::
+
+    with CortexMemory.from_env() as memory:
+        response = memory.chat("Remind me about my diet goals.")
+        memory.ingest("User has decided to go vegan starting Monday.")
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from sentence_transformers import SentenceTransformer
+
+from cortex_memory.config import CortexConfig
+from cortex_memory.ingestion.ingestor import ingest_text_to_memory_graph
+from cortex_memory.llm.chat import build_llm_client, chat_with_assistant
+from cortex_memory.retrieval.retriever import WeightedMemoryRetriever
+
+
+class CortexMemory:
+    """
+    High-level orchestrator for the Cortex Memory system.
+
+    Manages the lifecycle of the LLM client, embedder, and Neo4j
+    retriever so callers don't need to wire them up manually.
+
+    Parameters
+    ----------
+    config : CortexConfig
+        Runtime configuration.  Build one with ``CortexConfig.from_env()``
+        or pass values explicitly.
+    embedder : SentenceTransformer | None
+        Optional pre-loaded embedding model.  If ``None``, one is
+        instantiated from ``config.embedder_model``.
+    """
+
+    def __init__(
+        self,
+        config: CortexConfig,
+        embedder: SentenceTransformer | None = None,
+    ) -> None:
+        self.config = config
+
+        # --- shared embedder (loaded once) ---
+        self._embedder: SentenceTransformer = (
+            embedder
+            if embedder is not None
+            else SentenceTransformer(config.embedder_model)
+        )
+
+        # --- LLM client ---
+        self._llm = build_llm_client(config)
+
+        # --- Neo4j retriever ---
+        self._retriever = WeightedMemoryRetriever(
+            config=config, embedder=self._embedder
+        )
+
+    # ------------------------------------------------------------------
+    # Factories
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_env(
+        cls,
+        dotenv_path: str | None = None,
+        embedder: SentenceTransformer | None = None,
+    ) -> "CortexMemory":
+        """
+        Convenience factory that reads configuration from environment
+        variables (and an optional ``.env`` file).
+
+        Parameters
+        ----------
+        dotenv_path : str | None
+            Path to a custom ``.env`` file.  Defaults to the project root.
+        embedder : SentenceTransformer | None
+            Bring-your-own embedder (useful when you already have one
+            loaded in the parent application).
+
+        Returns
+        -------
+        CortexMemory
+        """
+        config = CortexConfig.from_env(dotenv_path=dotenv_path)
+        return cls(config=config, embedder=embedder)
+
+    # ------------------------------------------------------------------
+    # Core API
+    # ------------------------------------------------------------------
+
+    def chat(
+        self,
+        user_input: str,
+        *,
+        chat_history: list[dict] | None = None,
+        top_k: int | None = None,
+        auto_ingest: bool = True,
+    ) -> str:
+        """
+        Retrieve relevant memories, generate an LLM response, optionally
+        ingest the user's message, and reinforce retrieved memories.
+
+        Parameters
+        ----------
+        user_input : str
+            The user's message.
+        chat_history : list[dict] | None
+            Prior conversation turns for multi-turn context.
+        top_k : int | None
+            Override the number of memories to retrieve for this call.
+        auto_ingest : bool
+            Whether to automatically attempt to ingest the user's message
+            after generating a response (default: ``True``).
+
+        Returns
+        -------
+        str
+            The assistant's response.
+        """
+        # 1. Retrieve
+        results = self._retriever.search_weighted_memories(user_input, top_k=top_k)
+        memories = [r["content"] for r in results]
+
+        # 2. Generate response
+        response = chat_with_assistant(
+            user_input,
+            self._llm,
+            chat_history=chat_history,
+            memories=memories,
+        )
+
+        # 3. Optionally ingest the query
+        if auto_ingest:
+            self.ingest(user_input, source="assistant_chat")
+
+        # 4. Reinforce retrieved memories
+        for result in results:
+            self._retriever.reinforce_memory(result["label"])
+
+        return response
+
+    def ingest(
+        self,
+        text: str,
+        *,
+        source: str = "upload",
+        tags: list[str] | None = None,
+    ) -> bool:
+        """
+        Evaluate *text* and persist it to the memory graph if worthy.
+
+        Parameters
+        ----------
+        text : str
+            Raw text to evaluate.
+        source : str
+            Provenance tag (e.g. ``"upload"``, ``"assistant_chat"``).
+        tags : list[str] | None
+            Additional keyword tags to attach to the stored memory nodes.
+
+        Returns
+        -------
+        bool
+            ``True`` if at least one chunk was ingested.
+        """
+        return ingest_text_to_memory_graph(
+            text,
+            config=self.config,
+            llm=self._llm,
+            embedder=self._embedder,
+            source=source,
+            tags=tags,
+        )
+
+    def retrieve(
+        self,
+        query: str,
+        top_k: int | None = None,
+    ) -> list[dict]:
+        """
+        Perform a raw weighted memory search without chat or ingestion.
+
+        Parameters
+        ----------
+        query : str
+            The search query.
+        top_k : int | None
+            Number of results to retrieve.
+
+        Returns
+        -------
+        list[dict]
+            Memory records sorted by weighted score.
+        """
+        return self._retriever.search_weighted_memories(query, top_k=top_k)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """Release Neo4j driver connections."""
+        self._retriever.close()
+
+    def __enter__(self) -> "CortexMemory":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()

cortex_memory/config.py

@@ -0,0 +1,112 @@
+"""
+cortex_memory.config
+~~~~~~~~~~~~~~~~~~~~
+Centralised configuration for the Cortex Memory package.
+
+All runtime parameters live here so no individual module ever
+calls os.getenv() directly.  Construct with CortexConfig.from_env()
+to pull values from a .env file, or pass them explicitly.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from dotenv import load_dotenv
+
+
+@dataclass
+class CortexConfig:
+    """
+    Holds every tunable parameter for the Cortex Memory system.
+
+    Parameters
+    ----------
+    neo4j_uri : str
+        Bolt URI for the Neo4j instance (e.g. ``bolt://localhost:7687``).
+    neo4j_username : str
+        Neo4j username (default: ``"neo4j"``).
+    neo4j_password : str
+        Neo4j password.
+    groq_api_key : str
+        API key for Groq.
+    model : str
+        LLM model name served by Groq (default: ``"openai/gpt-oss-20b"``).
+    embedder_model : str
+        SentenceTransformer model name (default: ``"all-MiniLM-L6-v2"``).
+    top_k : int
+        Number of candidate memories fetched from the vector index
+        before weighted re-ranking (default: 5).
+    score_threshold : float
+        Minimum weighted score a memory must achieve to be returned
+        (default: 0.65).
+    chunk_max_chars : int
+        Maximum character width for text chunking (default: 400).
+    """
+
+    neo4j_uri: str
+    neo4j_username: str
+    neo4j_password: str
+    groq_api_key: str
+
+    # --- LLM ---
+    model: str = "openai/gpt-oss-20b"
+
+    # --- Embedder ---
+    embedder_model: str = "all-MiniLM-L6-v2"
+
+    # --- Retrieval ---
+    top_k: int = 5
+    score_threshold: float = 0.65
+
+    # --- Ingestion ---
+    chunk_max_chars: int = 400
+
+    # ------------------------------------------------------------------
+    # Factory
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def from_env(cls, dotenv_path: str | None = None) -> "CortexConfig":
+        """
+        Build a ``CortexConfig`` from environment variables.
+
+        Loads a ``.env`` file if present (or from *dotenv_path* if given).
+        Required env vars:
+          - ``NEO4J_URI``
+          - ``NEO4J_PASSWORD``
+          - ``GROQ_API_KEY``
+
+        Optional env vars (have sensible defaults):
+          - ``NEO4J_USERNAME`` (default ``"neo4j"``)
+          - ``CORTEX_MODEL``
+          - ``CORTEX_EMBEDDER``
+          - ``CORTEX_TOP_K``
+          - ``CORTEX_SCORE_THRESHOLD``
+          - ``CORTEX_CHUNK_MAX_CHARS``
+        """
+        load_dotenv(dotenv_path=dotenv_path)
+
+        neo4j_uri = os.getenv("NEO4J_URI", "")
+        neo4j_username = os.getenv("NEO4J_USERNAME", "neo4j")
+        neo4j_password = os.getenv("NEO4J_PASSWORD", "")
+        groq_api_key = os.getenv("GROQ_API_KEY", "")
+
+        if not neo4j_uri:
+            raise EnvironmentError("NEO4J_URI is not set in environment.")
+        if not neo4j_password:
+            raise EnvironmentError("NEO4J_PASSWORD is not set in environment.")
+        if not groq_api_key:
+            raise EnvironmentError("GROQ_API_KEY is not set in environment.")
+
+        return cls(
+            neo4j_uri=neo4j_uri,
+            neo4j_username=neo4j_username,
+            neo4j_password=neo4j_password,
+            groq_api_key=groq_api_key,
+            model=os.getenv("CORTEX_MODEL", "openai/gpt-oss-20b"),
+            embedder_model=os.getenv("CORTEX_EMBEDDER", "all-MiniLM-L6-v2"),
+            top_k=int(os.getenv("CORTEX_TOP_K", "5")),
+            score_threshold=float(os.getenv("CORTEX_SCORE_THRESHOLD", "0.65")),
+            chunk_max_chars=int(os.getenv("CORTEX_CHUNK_MAX_CHARS", "400")),
+        )

cortex_memory/graph/__init__.py

@@ -0,0 +1,4 @@
+"""cortex_memory.graph package."""
+from cortex_memory.graph.memory_graph import MemoryGraph
+
+__all__ = ["MemoryGraph"]

cortex_memory/graph/memory_graph.py

@@ -0,0 +1,87 @@
+"""
+cortex_memory.graph.memory_graph
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Low-level Neo4j persistence layer.
+
+``MemoryGraph`` is the only class that knows about Cypher — every
+other module calls its public methods rather than writing queries
+directly.
+"""
+
+from __future__ import annotations
+
+from neo4j import GraphDatabase
+
+
+class MemoryGraph:
+    """
+    Thin wrapper around the Neo4j driver that handles upsert operations
+    for ``Memory`` and ``Entity`` nodes.
+
+    Parameters
+    ----------
+    uri : str
+        Bolt URI for the Neo4j instance.
+    username : str
+        Neo4j username.
+    password : str
+        Neo4j password.
+    """
+
+    def __init__(self, uri: str, username: str, password: str) -> None:
+        self.driver = GraphDatabase.driver(uri, auth=(username, password))
+
+    # ------------------------------------------------------------------
+    # Write operations
+    # ------------------------------------------------------------------
+
+    def upsert_memory(self, memory: dict) -> None:
+        """
+        Merge a ``Memory`` node by ``id`` and set all scalar properties.
+        Each name in ``memory["related_entities"]`` is merged as an
+        ``Entity`` node linked via ``:RELATED_TO``.
+
+        Parameters
+        ----------
+        memory : dict
+            Dictionary with keys: id, type, label, content, source,
+            created_at, last_accessed, importance, stability, status,
+            tags, embedding, related_entities.
+        """
+        query = """
+        MERGE (m:Memory {id: $id})
+        SET m += {
+            type:          $type,
+            label:         $label,
+            content:       $content,
+            source:        $source,
+            created_at:    datetime($created_at),
+            last_accessed: datetime($last_accessed),
+            importance:    $importance,
+            stability:     $stability,
+            status:        $status,
+            tags:          $tags,
+            embedding:     $embedding
+        }
+        WITH m
+        UNWIND $related_entities AS entity
+        MERGE (e:Entity {name: entity})
+        MERGE (m)-[:RELATED_TO]->(e)
+        RETURN m.id AS id
+        """
+        with self.driver.session() as session:
+            session.run(query, **memory)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying Neo4j driver connection."""
+        self.driver.close()
+
+    def __enter__(self) -> "MemoryGraph":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()

cortex_memory/ingestion/__init__.py

@@ -0,0 +1,14 @@
+"""cortex_memory.ingestion package."""
+from cortex_memory.ingestion.ingestor import (
+    ingest_text_to_memory_graph,
+    chunk_text,
+    extract_query_tags,
+    get_all_entities,
+)
+
+__all__ = [
+    "ingest_text_to_memory_graph",
+    "chunk_text",
+    "extract_query_tags",
+    "get_all_entities",
+]