friday-memory 1.2.0__py3-none-any.whl

friday/__init__.py

@@ -0,0 +1,32 @@
+"""Friday — Persistent Cognitive Memory Layer for AI Coding Agents.
+
+Official Python SDK for self-hosted Friday cognitive memory server.
+"""
+
+from .client import AsyncFriday, Friday
+from .exceptions import (
+    FridayAPIError,
+    FridayAuthenticationError,
+    FridayConnectionError,
+    FridayError,
+    FridayNotFoundError,
+)
+from .types import Fact, GraphData, HealthStatus, MemoryResult, SearchResult
+
+__version__ = "1.2.0"
+
+__all__ = [
+    "Friday",
+    "AsyncFriday",
+    "FridayError",
+    "FridayConnectionError",
+    "FridayAuthenticationError",
+    "FridayNotFoundError",
+    "FridayAPIError",
+    "Fact",
+    "MemoryResult",
+    "SearchResult",
+    "HealthStatus",
+    "GraphData",
+    "__version__",
+]

friday/client.py

@@ -0,0 +1,298 @@
+"""Friday Python SDK — Core Client Implementation.
+
+Provides synchronous (`Friday`) and asynchronous (`AsyncFriday`) clients
+for interacting with the self-hosted Friday cognitive memory substrate.
+"""
+
+import os
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from .exceptions import (
+    FridayAPIError,
+    FridayAuthenticationError,
+    FridayConnectionError,
+    FridayNotFoundError,
+)
+from .types import Fact, GraphData, HealthStatus, MemoryResult
+
+
+def _resolve_config(
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> tuple[str, str]:
+    resolved_url = (
+        base_url
+        or os.environ.get("FRIDAY_URL")
+        or os.environ.get("BRAIN_URL")
+        or "http://localhost:8000"
+    ).rstrip("/")
+    resolved_key = (
+        api_key or os.environ.get("FRIDAY_API_KEY") or os.environ.get("BRAIN_API_KEY") or ""
+    )
+    return resolved_url, resolved_key
+
+
+def _handle_response_error(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+
+    if response.status_code == 401:
+        raise FridayAuthenticationError("Invalid or missing API key.")
+    elif response.status_code == 404:
+        raise FridayNotFoundError(f"Resource not found: {response.url}")
+    else:
+        raise FridayAPIError(
+            message=f"HTTP {response.status_code}",
+            status_code=response.status_code,
+            response_text=response.text,
+        )
+
+
+class Friday:
+    """Synchronous Friday Cognitive Memory Client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        transport: Optional[httpx.BaseTransport] = None,
+    ):
+        self.base_url, self.api_key = _resolve_config(api_key, base_url)
+        self.headers = {
+            "Content-Type": "application/json",
+            "X-Brain-Key": self.api_key,
+        }
+        self.client = httpx.Client(
+            base_url=self.base_url,
+            headers=self.headers,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def __enter__(self) -> "Friday":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self.client.close()
+
+    def health(self) -> HealthStatus:
+        """Check the health status of all Friday memory layers."""
+        try:
+            r = self.client.get("/health")
+            _handle_response_error(r)
+            return r.json()
+        except httpx.ConnectError as e:
+            raise FridayConnectionError(
+                f"Could not connect to Friday at {self.base_url}: {e}"
+            ) from e
+        except httpx.TimeoutException as e:
+            raise FridayConnectionError(
+                f"Connection timed out connecting to Friday at {self.base_url}: {e}"
+            ) from e
+
+    def add_memory(self, content: str, project: str = "default") -> MemoryResult:
+        """Store an architectural decision or context chunk into episodic memory."""
+        try:
+            payload = {"content": content, "project": project}
+            r = self.client.post("/add", json=payload)
+            _handle_response_error(r)
+            return r.json()
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise FridayConnectionError(f"Network error adding memory: {e}") from e
+
+    def search(self, query: str, project: Optional[str] = None) -> Dict[str, Any]:
+        """Search memory layers semantically for relevant architectural context."""
+        try:
+            payload: Dict[str, Any] = {"query": query}
+            if project:
+                payload["project"] = project
+            r = self.client.post("/search", json=payload)
+            _handle_response_error(r)
+            return r.json()
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise FridayConnectionError(f"Network error searching memory: {e}") from e
+
+    def add_fact(self, content: str) -> Dict[str, Any]:
+        """Commit an atomic, versioned ground-truth fact to the facts ledger."""
+        try:
+            payload = {"content": content}
+            r = self.client.post("/facts", json=payload)
+            _handle_response_error(r)
+            return r.json()
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise FridayConnectionError(f"Network error adding fact: {e}") from e
+
+    def get_facts(self, include_superseded: bool = False) -> List[Fact]:
+        """Retrieve verified ground-truth facts from the ledger."""
+        try:
+            url = "/facts?include_superseded=true" if include_superseded else "/facts"
+            r = self.client.get(url)
+            _handle_response_error(r)
+            data = r.json()
+            return data.get("facts", [])
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise FridayConnectionError(f"Network error retrieving facts: {e}") from e
+
+    def get_context(self, query: Optional[str] = None, target: str = "agents") -> str:
+        """Export compiled architectural directives and verified facts for prompt injection."""
+        try:
+            url = f"/export/persona?target={target}"
+            r = self.client.get(url)
+            _handle_response_error(r)
+            return r.text
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise FridayConnectionError(f"Network error retrieving context: {e}") from e
+
+    def get_graph_data(self) -> GraphData:
+        """Fetch all entities and typed relationships from the Neo4j knowledge graph."""
+        try:
+            r = self.client.get("/api/graph-data")
+            _handle_response_error(r)
+            return r.json()
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise FridayConnectionError(f"Network error retrieving graph data: {e}") from e
+
+    def ingest(
+        self, text: str, filename: Optional[str] = None, source: str = "document"
+    ) -> Dict[str, Any]:
+        """Batch ingest architectural specifications or documentation into the knowledge base."""
+        try:
+            payload = {"text": text, "source": source}
+            if filename:
+                payload["filename"] = filename
+            r = self.client.post("/ingest", json=payload)
+            _handle_response_error(r)
+            return r.json()
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise FridayConnectionError(f"Network error ingesting document: {e}") from e
+
+
+class AsyncFriday:
+    """Asynchronous Friday Cognitive Memory Client."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ):
+        self.base_url, self.api_key = _resolve_config(api_key, base_url)
+        self.headers = {
+            "Content-Type": "application/json",
+            "X-Brain-Key": self.api_key,
+        }
+        self.client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=self.headers,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    async def __aenter__(self) -> "AsyncFriday":
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self.client.aclose()
+
+    async def health(self) -> HealthStatus:
+        """Check the health status of all Friday memory layers."""
+        try:
+            r = await self.client.get("/health")
+            _handle_response_error(r)
+            return r.json()
+        except httpx.ConnectError as e:
+            raise FridayConnectionError(
+                f"Could not connect to Friday at {self.base_url}: {e}"
+            ) from e
+        except httpx.TimeoutException as e:
+            raise FridayConnectionError(
+                f"Connection timed out connecting to Friday at {self.base_url}: {e}"
+            ) from e
+
+    async def add_memory(self, content: str, project: str = "default") -> MemoryResult:
+        """Store an architectural decision or context chunk into episodic memory."""
+        try:
+            payload = {"content": content, "project": project}
+            r = await self.client.post("/add", json=payload)
+            _handle_response_error(r)
+            return r.json()
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise FridayConnectionError(f"Network error adding memory: {e}") from e
+
+    async def search(self, query: str, project: Optional[str] = None) -> Dict[str, Any]:
+        """Search memory layers semantically for relevant architectural context."""
+        try:
+            payload: Dict[str, Any] = {"query": query}
+            if project:
+                payload["project"] = project
+            r = await self.client.post("/search", json=payload)
+            _handle_response_error(r)
+            return r.json()
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise FridayConnectionError(f"Network error searching memory: {e}") from e
+
+    async def add_fact(self, content: str) -> Dict[str, Any]:
+        """Commit an atomic, versioned ground-truth fact to the facts ledger."""
+        try:
+            payload = {"content": content}
+            r = await self.client.post("/facts", json=payload)
+            _handle_response_error(r)
+            return r.json()
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise FridayConnectionError(f"Network error adding fact: {e}") from e
+
+    async def get_facts(self, include_superseded: bool = False) -> List[Fact]:
+        """Retrieve verified ground-truth facts from the ledger."""
+        try:
+            url = "/facts?include_superseded=true" if include_superseded else "/facts"
+            r = await self.client.get(url)
+            _handle_response_error(r)
+            data = r.json()
+            return data.get("facts", [])
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise FridayConnectionError(f"Network error retrieving facts: {e}") from e
+
+    async def get_context(self, query: Optional[str] = None, target: str = "agents") -> str:
+        """Export compiled architectural directives and verified facts for prompt injection."""
+        try:
+            url = f"/export/persona?target={target}"
+            r = await self.client.get(url)
+            _handle_response_error(r)
+            return r.text
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise FridayConnectionError(f"Network error retrieving context: {e}") from e
+
+    async def get_graph_data(self) -> GraphData:
+        """Fetch all entities and typed relationships from the Neo4j knowledge graph."""
+        try:
+            r = await self.client.get("/api/graph-data")
+            _handle_response_error(r)
+            return r.json()
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise FridayConnectionError(f"Network error retrieving graph data: {e}") from e
+
+    async def ingest(
+        self, text: str, filename: Optional[str] = None, source: str = "document"
+    ) -> Dict[str, Any]:
+        """Batch ingest architectural specifications or documentation into the knowledge base."""
+        try:
+            payload = {"text": text, "source": source}
+            if filename:
+                payload["filename"] = filename
+            r = await self.client.post("/ingest", json=payload)
+            _handle_response_error(r)
+            return r.json()
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise FridayConnectionError(f"Network error ingesting document: {e}") from e

friday/exceptions.py

@@ -0,0 +1,34 @@
+"""Friday Python SDK — Custom Exceptions."""
+
+
+class FridayError(Exception):
+    """Base exception for all Friday SDK errors."""
+
+    pass
+
+
+class FridayConnectionError(FridayError):
+    """Raised when the client fails to connect to the Friday server or times out."""
+
+    pass
+
+
+class FridayAuthenticationError(FridayError):
+    """Raised when the API key is missing, invalid, or unauthorized (HTTP 401)."""
+
+    pass
+
+
+class FridayNotFoundError(FridayError):
+    """Raised when a requested resource is not found (HTTP 404)."""
+
+    pass
+
+
+class FridayAPIError(FridayError):
+    """Raised when the Friday API returns an unexpected error response."""
+
+    def __init__(self, message: str, status_code: int = 500, response_text: str = ""):
+        super().__init__(f"[{status_code}] {message}: {response_text}".strip())
+        self.status_code = status_code
+        self.response_text = response_text

friday/integrations/__init__.py

@@ -0,0 +1 @@
+"""Friday Python SDK — Framework Integrations."""

friday/integrations/langchain.py

@@ -0,0 +1,79 @@
+"""Friday LangChain Integration — Custom BaseRetriever."""
+
+from typing import Any, List, Optional
+
+from ..client import Friday
+
+try:
+    from langchain_core.callbacks import CallbackManagerForRetrieverRun
+    from langchain_core.documents import Document
+    from langchain_core.retrievers import BaseRetriever
+
+    _HAS_LANGCHAIN = True
+except ImportError:
+    _HAS_LANGCHAIN = False
+    BaseRetriever = None  # type: ignore
+    Document = None  # type: ignore
+    CallbackManagerForRetrieverRun = None  # type: ignore
+
+
+if _HAS_LANGCHAIN:
+
+    class FridayRetriever(BaseRetriever):  # type: ignore[misc]
+        """LangChain Retriever for Friday Cognitive Memory Layer.
+
+        Example:
+            ```python
+            from friday.integrations.langchain import FridayRetriever
+
+            retriever = FridayRetriever(api_key="secret", base_url="http://localhost:8000")
+            docs = retriever.invoke("What database do we use?")
+            ```
+        """
+
+        api_key: Optional[str] = None
+        base_url: Optional[str] = "http://localhost:8000"
+        project: str = "default"
+
+        def _get_relevant_documents(
+            self, query: str, *, run_manager: Optional[CallbackManagerForRetrieverRun] = None
+        ) -> List[Document]:
+            with Friday(api_key=self.api_key, base_url=self.base_url) as client:
+                res = client.search(query=query, project=self.project)
+                docs = []
+                results = res.get("results", {})
+
+                # Parse facts
+                for fact in results.get("layer2_facts", []):
+                    docs.append(Document(page_content=fact, metadata={"source": "friday_facts"}))
+
+                # Parse semantic chunks
+                for mem in results.get("layer3_semantic", []):
+                    docs.append(Document(page_content=mem, metadata={"source": "friday_semantic"}))
+
+                return docs
+
+else:
+
+    class FridayRetriever:  # type: ignore[no-redef]
+        """Stub FridayRetriever when langchain-core is not installed."""
+
+        def __init__(
+            self,
+            api_key: Optional[str] = None,
+            base_url: Optional[str] = "http://localhost:8000",
+            project: str = "default",
+            **kwargs: Any,
+        ):
+            self.api_key = api_key
+            self.base_url = base_url
+            self.project = project
+
+        def _get_relevant_documents(self, query: str, *args: Any, **kwargs: Any) -> Any:
+            raise ImportError(
+                "langchain-core is required to use FridayRetriever. "
+                "Install it via: pip install 'friday-memory[langchain]' or pip install langchain-core"
+            )
+
+        def invoke(self, input: str, *args: Any, **kwargs: Any) -> Any:
+            return self._get_relevant_documents(input, *args, **kwargs)

friday/types.py

@@ -0,0 +1,41 @@
+"""Friday Python SDK — Type Definitions."""
+
+from typing import Any, Dict, List, Optional
+
+from typing_extensions import TypedDict
+
+
+class Fact(TypedDict, total=False):
+    id: str
+    content: str
+    created_at: str
+    updated_at: str
+    version: int
+    status: str
+    source: str
+    replaces: Optional[str]
+
+
+class MemoryResult(TypedDict, total=False):
+    status: str
+    mem0_id: Optional[str]
+    chroma_id: Optional[str]
+    message: Optional[str]
+
+
+class SearchResult(TypedDict, total=False):
+    query: str
+    results: Dict[str, Any]
+
+
+class HealthStatus(TypedDict, total=False):
+    status: str
+    service: str
+    version: str
+    layers: Dict[str, str]
+    timestamp: float
+
+
+class GraphData(TypedDict, total=False):
+    nodes: List[Dict[str, Any]]
+    links: List[Dict[str, Any]]

friday_memory-1.2.0.dist-info/METADATA

@@ -0,0 +1,574 @@
+Metadata-Version: 2.5
+Name: friday-memory
+Version: 1.2.0
+Summary: Official Python SDK and self-hosted persistent cognitive memory layer for AI coding agents
+Project-URL: Homepage, https://github.com/friday-memory/friday
+Project-URL: Repository, https://github.com/friday-memory/friday.git
+Project-URL: Issues, https://github.com/friday-memory/friday/issues
+Author-email: Shobhit Singh <itskie7910@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude-code,cursor,knowledge-graph,mcp,memory,model-context-protocol,neo4j,persistent-memory,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Provides-Extra: server
+Requires-Dist: chromadb>=0.5.7; extra == 'server'
+Requires-Dist: fastapi>=0.115.0; extra == 'server'
+Requires-Dist: mem0ai>=0.1.29; extra == 'server'
+Requires-Dist: neo4j>=5.24.0; extra == 'server'
+Requires-Dist: openai>=1.45.0; extra == 'server'
+Requires-Dist: pydantic>=2.9.2; extra == 'server'
+Requires-Dist: python-dotenv>=1.0.1; extra == 'server'
+Requires-Dist: sentence-transformers>=3.1.0; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.30.6; extra == 'server'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<br>
+
+<img src="docs/assets/banner.png" alt="Friday - Persistent Cognitive Memory Layer for AI Coding Agents" width="100%" style="border-radius: 8px; border: 1px solid #1e293b;" />
+
+<br><br>
+
+# Friday
+
+**Self-hosted persistent cognitive memory layer for AI coding agents.**
+
+Persists architecture decisions, schemas, and constraints across sessions via the Model Context Protocol (MCP).
+
+<br>
+
+<p align="center">
+  <a href="https://github.com/friday-memory/friday/stargazers"><img src="https://img.shields.io/github/stars/friday-memory/friday?style=flat&color=334155&label=Stars" alt="GitHub Stars"/></a>
+  <a href="https://github.com/friday-memory/friday/releases"><img src="https://img.shields.io/badge/release-v1.2.0-334155?style=flat" alt="Release"/></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-334155?style=flat" alt="MIT License"/></a>
+  <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.11+-334155?style=flat" alt="Python 3.11+"/></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/protocol-MCP_2024--11--05-334155?style=flat" alt="MCP Protocol"/></a>
+  <a href="docker-compose.yml"><img src="https://img.shields.io/badge/docker-compose_ready-334155?style=flat" alt="Docker Compose Ready"/></a>
+  <a href="#deepeval-benchmarks"><img src="https://img.shields.io/badge/evals-deepeval_verified-334155?style=flat" alt="DeepEval Verified"/></a>
+</p>
+
+<br>
+
+<table>
+  <tr>
+    <td align="center"><a href="#the-problem-session-amnesia"><b>Overview</b></a></td>
+    <td align="center"><a href="#quickstart"><b>Quickstart</b></a></td>
+    <td align="center"><a href="#python-sdk-friday-memory"><b>Python SDK</b></a></td>
+    <td align="center"><a href="#client-setup-mcp"><b>Client Setup (MCP)</b></a></td>
+    <td align="center"><a href="#architecture"><b>Architecture</b></a></td>
+    <td align="center"><a href="#deepeval-benchmarks"><b>Benchmarks</b></a></td>
+    <td align="center"><a href="#api-reference"><b>API Reference</b></a></td>
+  </tr>
+</table>
+
+<br><br>
+
+<img src="docs/assets/synthetic_neural_cortex.png" alt="Friday Neural Studio — Interactive Knowledge Graph" width="100%" style="border-radius: 8px; border: 1px solid #1e293b;" />
+
+<br>
+<sub><i>Friday Neural Studio — Real-time WebGL knowledge graph visualizer rendering service topologies, entity dependencies, and versioned facts.</i></sub>
+
+<br><br>
+
+</div>
+
+---
+
+## The Problem: Session Amnesia
+
+Modern AI coding agents (Cursor, Claude Code, Antigravity, VS Code) excel at isolated code generation. However, in continuous engineering workflows, developers encounter a structural limitation: **Session Amnesia**.
+
+Current workarounds fall into two flawed patterns:
+
+```
+                  ┌─────────────────────────────────────────────────────────┐
+                  │          WHY STANDARD APPROACHES BREAK DOWN             │
+                  └─────────────────────────────────────────────────────────┘
+
+   1. Context Windows (RAM)           2. Static Rules Files             3. Standard Vector RAG
+  ┌─────────────────────────┐       ┌─────────────────────────┐       ┌─────────────────────────┐
+  │ • Ephemeral volatile    │       │ • Linear token tax      │       │ • Matches text phrasing,│
+  │   memory (clears on     │       │   (2,500 tokens burned  │       │   NOT system topology   │
+  │   every new thread)     │       │   on every trivial fix) │       │ • Blind to directed     │
+  │ • Lost-in-the-middle    │       │ • Stale rules accumu-   │       │   call graphs & schema  │
+  │   degradation on 50k+   │       │   late & conflict       │       │   dependencies          │
+  │   token prompts         │       │ • Zero cross-tool sync  │       │ • Hallucinates blast    │
+  │ • High latency & cost   │       │   (Cursor ≠ Claude CLI) │       │   radii of refactors    │
+  └─────────────────────────┘       └─────────────────────────┘       └─────────────────────────┘
+```
+
+1. **Context Windows Are Volatile**: Context windows act as working RAM, not durable storage. Clearing a thread or restarting an agent resets state. Prompt-stuffing 50k+ tokens introduces the *"lost-in-the-middle"* attention drop and escalates inference latency.
+2. **Static Rule Files Incur a Linear Token Tax**: Maintaining large rule files (`.cursorrules`, `AGENTS.md`) forces the model to re-read thousands of lines on every keystroke, leading to contradictory instructions and cross-editor fragmentation.
+3. **Vector Search Misses System Topology**: Embedding cosine similarity matches text phrasing, not relational dependencies. Vector search cannot traverse directed graphs:
+   $$\text{Table: accounts} \longrightarrow \text{FK: subscriptions} \longrightarrow \text{Service: BillingService} \longrightarrow \text{Worker: InvoicePoller}$$
+
+---
+
+## Architecture: Multi-Layer Cognitive Substrate
+
+Friday runs as a self-hosted background service providing a structured, four-tier memory substrate accessed via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io):
+
+```
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│               AI CODING CLIENTS (Cursor / Claude Code / Antigravity / VS Code)         │
+└───────────────────────────────────────────┬────────────────────────────────────────────┘
+                                            │
+                                4 MCP Tools (stdio / HTTP)
+                                ├── add_memory       (persist decisions & rationale)
+                                ├── add_fact         (versioned immutable truths)
+                                ├── memory_search    (targeted semantic recall)
+                                └── get_context      (compiled multi-layer prompt)
+                                            │
+                                            ▼
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│                                 FRIDAY COGNITIVE ENGINE                                │
+│                                                                                        │
+│   Layer 1: Facts Ledger         Layer 2: Episodic Memory       Layer 3: Graph Topology │
+│  ┌─────────────────────────┐   ┌───────────────────────────┐  ┌──────────────────────┐ │
+│  │ Versioned SQLite        │   │ Mem0 + ChromaDB           │  │ Neo4j Property Graph │ │
+│  │ • Deterministic truths  │   │ • Semantic decisions      │  │ • Directed call-trees│ │
+│  │ • Conflict detection    │   │ • Vector similarity       │  │ • Schema blast-radius│ │
+│  │ • Zero prompt overhead  │   │ • Sub-100ms retrieval     │  │ • Entity dependencies│ │
+│  └─────────────────────────┘   └───────────────────────────┘  └──────────────────────┘ │
+│                                                                                        │
+│   • Auto-Graph Pipeline: LLM extraction wires entities into Neo4j automatically.       │
+│   • Neural Studio: WebGL-based 3D graph visualizer for human and agent state auditing. │
+│   • Persona Synchronization: /export/persona compiles canonical rules on-demand.       │
+└────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Architectural Comparison Matrix
+
+| Capability | Static Prompts (`.cursorrules`) | Traditional Vector RAG | Friday Cognitive Substrate |
+| :--- | :---: | :---: | :---: |
+| **Cross-Session Persistence** | None (resets with thread) | Text chunks only | Full architectural state & decisions |
+| **Dependency Graph Traversal** | None | Lexical similarity only | Neo4j Directed Property Graph |
+| **Token Efficiency** | Burns 2,000–5,000 tokens/turn | Unfiltered chunk dumps | Targeted queries (~280 tokens/turn) |
+| **Toolchain Synchronization** | Isolated per editor config | Disconnected silos | Unified MCP across Cursor, Claude, CLI |
+| **Conflict Resolution** | Manual file editing required | Ingests conflicting chunks | Versioned Fact Ledger with status flags |
+| **Topology Auditing** | None | None | Neural Studio 3D interactive viewer |
+| **Deployment Model** | Local flat files | Cloud SaaS vendor lock-in | 100% Self-Hosted Docker Compose |
+
+---
+
+## DeepEval Benchmarks
+
+We evaluated five realistic engineering scenarios using the [DeepEval](https://deepeval.com) evaluation framework:
+
+1. **Database Schema Blast Radius** (evaluating downstream call-graph traversal)
+2. **Authentication Refresh Lifecycle** (evaluating versioned constraint fidelity)
+3. **Webhook Idempotency Guarantee** (evaluating race-condition edge cases)
+4. **Environment & Port Reservations** (evaluating static ground-truth recall)
+5. **Multi-Agent Toolchain Consistency** (evaluating cross-tool synchronization between Cursor and Claude CLI)
+
+| Memory Architecture | Contextual Precision | Contextual Recall | Faithfulness | Prompt Tokens / Turn | Session Retention |
+| :--- | :---: | :---: | :---: | :---: | :---: |
+| **Static Prompts (`.cursorrules`)** | 38.0% | 44.0% | 62.0% | 3,150 tokens | 15.0% (resets) |
+| **Naive Vector RAG (Vector Only)** | 64.0% | 58.0% | 74.0% | 1,820 tokens | 55.0% |
+| **Friday Cognitive Substrate** | **95.0%** | **93.0%** | **99.0%** | **280 tokens** | **100.0%** |
+
+#### Reproducing Benchmarks Locally
+```bash
+python benchmarks/benchmark_deepeval.py
+```
+
+---
+
+## Quickstart
+
+### Option A: One-Command Installation (Recommended)
+
+Run the automated installer to check dependencies, generate configuration keys, and boot the stack:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/friday-memory/friday/main/install.sh | bash
+```
+
+---
+
+### Option B: Manual Setup via Docker Compose
+
+**1. Clone the repository**
+```bash
+git clone https://github.com/friday-memory/friday.git
+cd friday
+cp .env.example .env
+```
+
+**2. Configure environment (`.env`)**
+```env
+# Master API key for endpoint security
+FRIDAY_API_KEY=choose_a_strong_password
+
+# LLM provider for automated graph extraction (DeepSeek or Groq)
+DEEPSEEK_API_KEY=your_api_key_here
+DEEPSEEK_BASE_URL=https://api.deepseek.com
+
+# Mem0 key for vector memory
+MEM0_API_KEY=your_mem0_key_here
+
+# Neo4j database credentials
+NEO4J_PASSWORD=choose_a_secure_db_password
+```
+
+**3. Launch services**
+```bash
+make docker-up
+# or: docker compose up -d
+```
+
+Services initialized:
+- **Friday Gateway API**: `http://localhost:80` (or `http://localhost:8000`)
+- **Neo4j Browser**: `http://localhost:7474`
+- **Neural Studio UI**: `http://localhost/`
+
+**4. Verify health**
+```bash
+curl http://localhost/health
+```
+
+**5. Persist initial context**
+```bash
+curl -X POST http://localhost/add \
+  -H "X-Brain-Key: your_strong_password" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "content": "Authentication uses JWT access tokens (15m expiration) with httpOnly refresh cookies. Implementation in gateway/auth.py.",
+    "project": "CoreApp"
+  }'
+```
+
+---
+
+## Python SDK (`friday-memory`)
+
+Connect your agentic workflows, LangChain pipelines, or autonomous scripts directly to Friday with zero boilerplate:
+
+```bash
+pip install friday-memory
+```
+
+### Synchronous Client
+
+```python
+from friday import Friday
+
+# Automatically resolves FRIDAY_URL and FRIDAY_API_KEY from environment
+with Friday(api_key="your_secret_key", base_url="http://localhost:8000") as client:
+    # 1. Health check
+    status = client.health()
+    print("Friday Status:", status["status"])
+
+    # 2. Store architectural decision
+    client.add_memory(
+        "PostgreSQL 16 selected with pgvector for hybrid retrieval",
+        project="backend-api",
+    )
+
+    # 3. Commit immutable ground-truth fact
+    client.add_fact("Production database endpoint is db.internal.net:5432")
+
+    # 4. Multi-layer search (L2 Facts + L3 ChromaDB + L4 Knowledge Graph)
+    context = client.search("database connection configuration", project="backend-api")
+    print(context["results"])
+```
+
+### Asynchronous Client (FastAPI / Agent Workers)
+
+```python
+import asyncio
+from friday import AsyncFriday
+
+async def main():
+    async with AsyncFriday(api_key="your_secret_key") as client:
+        # Commit context concurrently
+        await client.add_memory("Redis cluster deployed for token bucket rate limiting")
+        facts = await client.get_facts()
+        print(f"Verified facts count: {len(facts)}")
+
+asyncio.run(main())
+```
+
+### LangChain Integration (`FridayRetriever`)
+
+```bash
+pip install "friday-memory[langchain]"
+```
+
+```python
+from friday.integrations.langchain import FridayRetriever
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_openai import ChatOpenAI
+
+retriever = FridayRetriever(
+    api_key="your_secret_key",
+    base_url="http://localhost:8000",
+    project="reeldm",
+)
+
+# Connect directly to LCEL chains
+prompt = ChatPromptTemplate.from_template("""Answer using verified system memory:
+{context}
+
+Question: {question}""")
+
+chain = {"context": retriever, "question": RunnablePassthrough()} | prompt | ChatOpenAI()
+```
+
+---
+
+## Client Setup (MCP)
+
+Friday provides an official Model Context Protocol (MCP) server over `stdio` or HTTP, enabling real-time context retrieval for all supported IDEs.
+
+```
+ ┌───────────────────────┐
+ │   Cursor (Desktop)    │──┐
+ └───────────────────────┘  │
+ ┌───────────────────────┐  │
+ │    Claude Code CLI    │──┼── MCP Protocol (stdio transport)
+ └───────────────────────┘  │   FRIDAY_URL="http://127.0.0.1:8000"
+ ┌───────────────────────┐  │   BRAIN_API_KEY="your_secret_key"
+ │    Antigravity IDE    │──┤
+ └───────────────────────┘  │
+ ┌───────────────────────┐  │
+ │  Windsurf / VS Code   │──┘
+ └───────────────────────┘
+                            ▼
+             ┌──────────────────────────────┐
+             │     FRIDAY CENTRAL BRAIN     │
+             │   (Localhost or Remote VM)   │
+             │   FastAPI + Mem0 + Neo4j     │
+             └──────────────────────────────┘
+```
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Add to `.cursor/mcp.json` in your project or globally in **Cursor Settings → MCP**:
+
+```json
+{
+  "mcpServers": {
+    "friday": {
+      "command": "python",
+      "args": ["-m", "mcp.server"],
+      "cwd": "/path/to/friday",
+      "env": {
+        "FRIDAY_URL": "http://localhost:8000",
+        "BRAIN_API_KEY": "your_secret_key"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Claude Code CLI</b></summary>
+
+Register Friday directly via CLI:
+
+```bash
+claude mcp add friday \
+  -e FRIDAY_URL="http://localhost:8000" \
+  -e BRAIN_API_KEY="your_secret_key" \
+  -- python -m mcp.server
+```
+</details>
+
+<details>
+<summary><b>Antigravity IDE</b></summary>
+
+Add to `~/.gemini/config/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "friday": {
+      "command": "python",
+      "args": ["-m", "mcp.server"],
+      "cwd": "/path/to/friday",
+      "env": {
+        "FRIDAY_URL": "http://localhost:8000",
+        "BRAIN_API_KEY": "your_secret_key"
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>VS Code (Cline / Roo Code)</b></summary>
+
+Add to your VS Code MCP configuration:
+
+```json
+{
+  "cline.mcpServers": {
+    "friday": {
+      "command": "python",
+      "args": ["-m", "mcp.server"],
+      "cwd": "/path/to/friday",
+      "env": {
+        "FRIDAY_URL": "http://localhost:8000",
+        "BRAIN_API_KEY": "your_secret_key"
+      }
+    }
+  }
+}
+```
+</details>
+
+---
+
+## Tool Reference
+
+Connected agents automatically access four core MCP primitives:
+
+| Primitive | Purpose | Trigger Phase |
+| :--- | :--- | :--- |
+| `get_context` | Ingests active verified facts and recent context. | Session initialization. |
+| `memory_search` | Queries vector and graph indices for architectural decisions. | Prior to answering technical questions. |
+| `add_memory` | Records implementation details, rationale, and tradeoffs. | Post-implementation or bug resolution. |
+| `add_fact` | Commits versioned, immutable ground truths (ports, stack, schemas). | Architectural declarations. |
+
+---
+
+## Dynamic Directives Export (`/export/persona`)
+
+Friday can compile stored facts and architectural constraints into synchronized markdown directives on-demand, preventing rules drift across teams:
+
+```bash
+# Export canonical AGENTS.md
+curl -s "http://localhost/export/persona?target=agents" \
+  -H "X-Brain-Key: your_key" > AGENTS.md
+
+# Export Cursor .cursorrules
+curl -s "http://localhost/export/persona?target=cursor" \
+  -H "X-Brain-Key: your_key" > .cursorrules
+```
+
+---
+
+## Features
+
+### 1. Automated Knowledge Graph Extraction
+Every memory written via `add_memory` is analyzed asynchronously. Entities and typed relations are automatically wired into Neo4j without manual schema definitions:
+
+```
+Input:
+"Billing engine connects to Stripe API for recurring charges. Webhook dispatched to /api/webhooks/stripe."
+
+Extracted Graph Nodes & Edges:
+  (:Service {name: "BillingEngine"}) -[:CONNECTS_TO]-> (:API {name: "Stripe"})
+  (:API {name: "Stripe"}) -[:DISPATCHES_TO]-> (:Endpoint {path: "/api/webhooks/stripe"})
+```
+
+### 2. Neural Studio (3D Topology Visualizer)
+A browser-based WebGL graph explorer (Three.js) for auditing agent memory:
+- **Cluster Topologies**: Visualizes architectural components as a 3D force-directed graph.
+- **Entity Inspector**: Inspect node connections, versioned facts, and raw vector chunks.
+- **Live CRUD**: Create, rename, or link entities directly within the visual interface.
+- **High-Resolution Export**: Export topology diagrams for technical documentation.
+
+### 3. Versioned Facts Ledger
+Deterministic project constants are recorded with immutable version history. Outdated statements are superseded rather than overwritten, preserving an audit trail:
+
+```bash
+# Add initial constraint
+POST /facts -> {"content": "PostgreSQL 16 running on port 5432"}
+# Recorded: id="c41b8a9", superseded=false
+
+# Update constraint
+POST /facts -> {"content": "Migrated database to Aurora PostgreSQL on port 5432"}
+# Prior fact marked superseded=true; active fact updated.
+```
+
+---
+
+## Repository Structure
+
+```
+friday/
+├── gateway/                 # FastAPI REST application & routing
+├── layers/                  # Pluggable storage adapters (SQLite, ChromaDB, Neo4j)
+├── pipelines/               # Background entity extraction & fact pipelines
+├── orchestrator/            # Multi-layer retrieval router
+├── mcp/                     # Model Context Protocol stdio server
+├── studio/                  # Three.js Neural Studio visualizer
+├── benchmarks/              # DeepEval evaluation suite
+├── tests/                   # Pytest test suite
+├── docker-compose.yml       # Production container definition
+├── Makefile                 # Developer task automation
+└── pyproject.toml           # Tooling & packaging configuration
+```
+
+---
+
+## API Reference
+
+All authenticated endpoints require the `X-Brain-Key` request header.
+
+| Method | Path | Auth | Description |
+| :---: | :--- | :---: | :--- |
+| `GET` | `/` | No | Serves Neural Studio visualizer. |
+| `GET` | `/health` | No | Layered health status check. |
+| `POST` | `/add` | Yes | Ingest memory and trigger background graph extraction. |
+| `POST` | `/facts` | Yes | Record or update a versioned fact. |
+| `GET` | `/facts` | No | List active ground-truth facts. |
+| `POST` | `/search` | Yes | Semantic search across vector stores. |
+| `POST` | `/ingest` | Yes | Batch ingest architectural specifications. |
+| `GET` | `/export/persona` | Yes | Export synchronized IDE rules (`agents` or `cursor`). |
+| `GET` | `/api/graph-data` | No | Fetch nodes and edges for 3D visualizer. |
+| `POST` | `/api/node/create` | Yes | Create a graph entity node. |
+| `DELETE` | `/api/node/{id}` | Yes | Delete an entity and cascading relationships. |
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+make install
+
+# Run test suite
+make test
+
+# Code formatting & linting
+make lint
+make format
+
+# Start local dev server
+make dev
+```
+
+---
+
+## Contributing
+
+Review [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines, commit conventions, and architectural standards.
+
+---
+
+## License
+
+Friday is licensed under the [MIT License](LICENSE).

friday_memory-1.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+friday/__init__.py,sha256=RxeiEKB0c7iFo3_kreu2vcAuGda11KGloZd4q8064pU,718
+friday/client.py,sha256=30uI5r2hTgSGGAT6-rCberKgNX90aC6p7j7iwQdp4g0,11893
+friday/exceptions.py,sha256=U2jTIZk-71i2IK4555CGSw7BuI6ZXsu0eYP5wCpto80,903
+friday/types.py,sha256=DqRzODKbsvntfWmvTxFGqe3gAUrnIq0Ky02g_5Ec8Hc,802
+friday/integrations/__init__.py,sha256=e7f70LYhSEhrUkdDstgUluF8Wz2EXIbY85ukBx7Rx5w,52
+friday/integrations/langchain.py,sha256=T40JaQKxXkcAqO_IwOEVqQeMx23fbi1H4bb3IV1b8bw,2828
+friday_memory-1.2.0.dist-info/METADATA,sha256=N2cYnddeJL2q_fLEfayNQrGPqGuODwGJyDwrnm_Q-PM,24283
+friday_memory-1.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+friday_memory-1.2.0.dist-info/licenses/LICENSE,sha256=rxQEFijI8CsGZ6vgRmUDavcaHp6y5yeii-6RXrYTkfc,1076
+friday_memory-1.2.0.dist-info/RECORD,,

friday_memory-1.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

friday_memory-1.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Friday Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.