Friday

An open-source, self-hosted persistent cognitive memory layer for AI coding agents (Cursor, Claude, VS Code).
Persists architecture decisions, schemas, and preferences across sessions via the Model Context Protocol (MCP).

🚀 Quickstart

🔌 IDE Setup

📊 Benchmarks

✨ Features

🏗️ Architecture

🗺️ Roadmap

_{Live Neural Studio (Holosphere 4.0) — 3D Synthetic Neural Cortex mapping cognitive memory constellations across anatomical cybernetic lobes with active synaptic action potentials.}

Modern AI coding agents (Cursor, Claude Code, Antigravity, Copilot) are exceptionally capable at isolated code generation. However, in production engineering environments, developers repeatedly hit the same structural wall: Session Amnesia.

Most teams attempt to solve this with either massive prompt files (.cursorrules, AGENTS.md) or generic vector search (RAG). Both approaches break down under real-world engineering constraints:

                  ┌─────────────────────────────────────────────────────────┐
                  │          WHY STANDARD APPROACHES BREAK DOWN             │
                  └─────────────────────────────────────────────────────────┘

   1. Context Windows (RAM)           2. Static Rules Files             3. Vector Search (RAG)
  ┌─────────────────────────┐       ┌─────────────────────────┐       ┌─────────────────────────┐
  │ • Ephemeral volatile    │       │ • Linear token tax      │       │ • Matches text phrasing,│
  │   memory (clears on     │       │   (2,500 tokens burned  │       │   NOT system topology   │
  │   every new thread)     │       │   on every typo 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    │
  └─────────────────────────┘       └─────────────────────────┘       └─────────────────────────┘

Context windows are working memory (volatile RAM), not storage. When you close a chat tab, trigger context compaction, or restart an agent, memory resets to zero. Furthermore, stuffing 50,000+ tokens of documentation into the prompt induces the well-documented "lost-in-the-middle" phenomenon: model attention degrades, subtle constraints are overlooked, and per-query latency and token bills skyrocket.

Maintaining 600-line Markdown files (.cursorrules, AGENTS.md) introduces severe operational drag:

• The Token Tax: You burn 2,000–3,000 prompt tokens on every interaction—even when merely asking the model to fix CSS padding.
• Knowledge Decay & Conflict: Over months, rules rot. One section says "use Axios", another says "use fetch". The model receives contradictory constraints and behaves erratically.
• Toolchain Fragmentation: Your Cursor rules are inaccessible to your Claude Code terminal CLI, your CI pipeline bots, or your teammates. There is no Single Source of Truth.

Vector embeddings calculate lexical and semantic cosine similarity, not system topology or state:

• The Failure Mode: Ask an agent: "What breaks if I rename the user_id column in the accounts table?"
• Standard vector search retrieves files containing the string "user_id". It cannot traverse directed dependency graphs: $$\text{Table: accounts} \longrightarrow \text{FK: subscriptions} \longrightarrow \text{Service: BillingService} \longrightarrow \text{Worker: InvoicePoller}$$
• Software architectures are directed graphs, not flat text documents. Without a relational graph database, agents cannot predict the blast radius of structural changes.

Friday runs as an independent, 24/7 self-hosted service providing a multi-tiered cognitive architecture accessible by all your tools via the Model Context Protocol (MCP):

┌────────────────────────────────────────────────────────────────────────────────────────┐
│               YOUR CODING AGENTS (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 CENTRAL COGNITIVE BRAIN                            │
│                                                                                        │
│   Layer 1: Facts Ledger         Layer 2: Episodic Memory       Layer 3: Graph Topology │
│  ┌─────────────────────────┐   ┌───────────────────────────┐  ┌──────────────────────┐ │
│  │ Versioned Facts         │   │ Mem0 + ChromaDB           │  │ Neo4j Property Graph │ │
│  │                         │   │                           │  │                      │ │
│  │ • Absolute ground truth │   │ • Chronological decisions │  │ • (:Endpoint)-[:CALLS│ │
│  │ • 0 token prompt tax    │   │ • Cross-session context   │  │ • (:Service)-[:WRITES│ │
│  │ • Conflict resolution   │   │ • 90% fewer tokens        │  │ • Entity call trees  │ │
│  └─────────────────────────┘   └───────────────────────────┘  └──────────────────────┘ │
│                                                                                        │
│   ⚡ Autonomous Graph Engine: Every memory → background extraction → Neo4j graph       │
│   🎨 Neural Studio: Live interactive visualizer for human & agent cognitive auditing  │
│   🔄 Dynamic Persona Export: /export/persona endpoint feeds synchronized rules to IDEs │
└────────────────────────────────────────────────────────────────────────────────────────┘

To quantify the architectural difference between flat prompt rules, basic vector search, and Friday's 4-layer cognitive substrate, we evaluated 5 complex software engineering scenarios using the DeepEval evaluation methodology:

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)

💡 Benchmark Highlights:

• 91% Token Reduction: Friday injects targeted snippets (~280 tokens) instead of burning 3,000+ tokens of raw prompt files on every keystroke.
• 96% Blast-Radius Capture: The Neo4j property graph captures foreign keys, service handlers, and API consumers that text-matching vector embeddings miss.
• Zero Knowledge Decay: Versioned facts ledger prevents contradictory constraints from confusing the agent.

Run the standalone evaluation suite in your terminal:

python benchmarks/benchmark_deepeval.py

Run the automated installer in your terminal. It verifies Docker, provisions containers, generates cryptographically secure keys, and prints ready-to-use Cursor and Claude Desktop MCP configurations:

curl -fsSL https://raw.githubusercontent.com/friday-memory/friday/main/install.sh | bash

Requirements: Docker + Docker Compose installed.
That's literally it. No Python setup. No database config. No services to manage manually.

Clone and configure

git clone https://github.com/friday-memory/friday.git
cd friday
cp .env.example .env

Fill in your .env — takes 60 seconds

# Set your own master password to protect your self-hosted server
FRIDAY_API_KEY=pick_any_secret_password_you_want

# DeepSeek (ultra-affordable — $0.14/M tokens)
# Get yours at: https://platform.deepseek.com
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Mem0 — generous free tier available
# Get yours at: https://mem0.ai
MEM0_API_KEY=m0-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Neo4j password — you choose this
NEO4J_PASSWORD=change_to_something_strong

Launch everything in one command

docker compose up -d

This starts:

• 🧠 Friday Brain on http://localhost
• 🕸️ Neo4j on http://localhost:7474
• 🎨 Neural Studio at http://localhost

Verify it's running

curl http://localhost/health
# {"status":"healthy","layers":{"neo4j":"ok","mem0":"ok","facts":"ok (0 entries)"}}

Store your first memory

curl -X POST http://localhost/add \
  -H "X-Brain-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "We use JWT with 15min access tokens + 7-day refresh. Implementation in gateway/auth.py. Never store tokens in localStorage — httpOnly cookies only.",
    "project": "MyApp"
  }'

Your AI now remembers. Forever. ✅

Instead of manually keeping .cursorrules or AGENTS.md in sync across teammates and workstations, Friday can dynamically compile your active verified facts and architectural constraints into a single markdown file:

# Pull canonical rules directly from Friday Central Brain
curl -s "http://localhost/export/persona?target=agents"   -H "X-Brain-Key: your_key" > AGENTS.md

# For Cursor .cursorrules format
curl -s "http://localhost/export/persona?target=cursor"   -H "X-Brain-Key: your_key" > .cursorrules

This guarantees all developers and AI agents in your organization adhere to the exact same architectural ground truths.

Friday is designed to be the central cognitive memory for all your AI coding tools.
Whether Friday runs locally on your machine or on a remote 24/7 cloud server (AWS EC2, VPS, Homelab), every agent connects to the same unified memory via the Model Context Protocol (MCP).

 ┌───────────────────────┐
 │   Cursor (Desktop)    │──┐
 └───────────────────────┘  │
 ┌───────────────────────┐  │
 │    Claude Code CLI    │──┼── MCP Protocol (stdio transport)
 └───────────────────────┘  │   FRIDAY_URL="http://your-server-ip:8000"
 ┌───────────────────────┐  │   BRAIN_API_KEY="your_secret_key"
 │    Antigravity IDE    │──┤
 └───────────────────────┘  │
 ┌───────────────────────┐  │
 │ Codex / Custom Agents │──┘
 └───────────────────────┘
                            ▼
             ┌──────────────────────────────┐
             │     FRIDAY CENTRAL BRAIN     │
             │   (Self-Hosted on Cloud/EC2) │
             │   FastAPI + Mem0 + Neo4j     │
             └──────────────────────────────┘

💡 Shared Brain Superpower: An architectural rule or decision stored by Claude Code in your terminal is immediately accessible to Cursor, Antigravity IDE, or Codex on your desktop. Zero manual syncing. One brain across your entire toolchain.

Pick your client below, paste the configuration, and restart your agent:

{
  "mcpServers": {
    "friday": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "cwd": "/path/to/friday",
      "env": {
        "FRIDAY_URL": "http://localhost:8000",
        "BRAIN_API_KEY": "your_key_from_env"
      }
    }
  }
}

claude mcp add friday   -e FRIDAY_URL="http://localhost:8000"   -e BRAIN_API_KEY="your_key_from_env"   -- python -m mcp.server

{
  "mcpServers": {
    "friday": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "cwd": "/path/to/friday",
      "env": {
        "FRIDAY_URL": "http://localhost:8000",
        "BRAIN_API_KEY": "your_key_from_env"
      }
    }
  }
}

{
  "mcpServers": {
    "friday": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "cwd": "/path/to/friday",
      "env": {
        "FRIDAY_URL": "http://localhost:8000",
        "BRAIN_API_KEY": "your_key_from_env"
      }
    }
  }
}

# Store memory from any agent script
curl -X POST http://<your-server-ip>:8000/add   -H "X-Brain-Key: your_key"   -H "Content-Type: application/json"   -d '{"content": "Refactored payment gateway to Stripe SDK v2.", "project": "MyApp"}'

# Retrieve relevant context before starting a prompt
curl -X POST http://<your-server-ip>:8000/search   -H "X-Brain-Key: your_key"   -H "Content-Type: application/json"   -d '{"query": "How is payments structured?", "project": "MyApp"}'

{
  "cline.mcpServers": {
    "friday": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "cwd": "/path/to/friday",
      "env": {
        "FRIDAY_URL": "http://localhost:8000",
        "BRAIN_API_KEY": "your_key_from_env"
      }
    }
  }
}

{
  "mcpServers": {
    "friday": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "cwd": "/path/to/friday",
      "env": {
        "FRIDAY_URL": "http://localhost:8000",
        "BRAIN_API_KEY": "your_key_from_env"
      }
    }
  }
}

📁 Pre-built config templates for all clients are available in examples/.

Every memory you store is automatically analyzed by an LLM (DeepSeek Flash).
Entities and relationships are extracted and wired into your Neo4j knowledge graph
without any manual input from you.

Input:
"MyApp uses Stripe for subscriptions. Plans: Free ($0), Pro ($19/mo), Team ($49/mo).
 PayPal handles international. Webhooks at /api/payments/webhook."

Auto-extracted graph:
  MyApp ────USES────────▶ Stripe
  MyApp ────USES────────▶ PayPal
  MyApp ────HAS_PLAN────▶ FreePlan     [price: $0]
  MyApp ────HAS_PLAN────▶ ProPlan      [price: $19/mo]
  MyApp ────HAS_PLAN────▶ TeamPlan     [price: $49/mo]
  Stripe ───WEBHOOK_AT──▶ /api/payments/webhook

No YAML. No manual tagging. Just store memories, and your knowledge graph builds itself.

A state-of-the-art WebGL / Three.js 3D cognitive brain studio — mapping your AI's knowledge graph onto an anatomical volumetric human cerebral cortex with real-time synaptic action potentials.

What you can do:

• 🧠 Volumetric 3D Cerebral Cortex — 4,000+ bioluminescent vertices shaped into bilateral hemispheres with gyri and sulci folds
• ⚡ Active Synaptic Action Potentials — live photon pulses travel along synaptic arcs simulating real cognitive action potentials
• 🌐 Dynamic Anatomical Lobe Bar — fly between Prefrontal (Executive directives), Cognitive Core, Visual Cortex (Ingress domain), Temporal (AI swarms), Parietal (Commerce), and Brainstem (Security)
• 🪐 Luminous Celestial Planet Orbs — clean, high-fidelity glowing spheres with soft atmospheres representing major knowledge hubs
• 🖱️ Cybernetic Inspector Drawer — click any entity to inspect connected synapses, live versioned facts, and retrieve deep semantic chunks directly from ChromaDB L3 Vector Store
• 🔍 Full-Text Cortex Search — camera auto-glides to focused entities with smooth damping flight curves
• 🎵 Procedural Web Audio SFX — subtle sci-fi clicks, hums, and warp chimes synthesizing the neural environment
• 📸 4K Hologram Snapshot — export high-resolution diagrams directly from the WebGL buffer
• ➕ Full CRUD operations: Create, Connect, Rename, and Delete entities directly from the 3D canvas

Discrete facts (rules, preferences, constants) are stored with immutable version history.
Old versions are superseded, never deleted. You always have a full audit trail.

# Store a fact
POST /facts  →  {"content": "We deploy on Ubuntu 22.04 LTS + systemd"}
# id: "a3f9e1b2", created_at: "2026-09-01", superseded: false

# 3 months later — upgraded
POST /facts  →  {"content": "We deploy on Ubuntu 24.04 LTS + Docker Compose"}
# Old fact: superseded: true  ← preserved for history
# New fact: superseded: false ← active version

# Your AI always gets the active version. Past versions auditable via API.
GET /facts?include_superseded=true

Instead of dumping your entire memory into every prompt, Friday uses ChromaDB vector search
to retrieve only the most relevant context for each query.

# Traditional RAG — expensive and noisy
context = all_memories  # 10,000 tokens of everything

# Friday — surgical precision
context = memory_search("JWT refresh token implementation")
# Returns: exactly the 3-5 memories about JWT, nothing else
# Cost: ~200 tokens vs 10,000  →  95% reduction

Once connected, your AI agent automatically calls Friday's tools. No prompting required.

┌──────────────────────────────────────────────────────────────────┐
│  Tool            │  When Your Agent Uses It                      │
├──────────────────┼───────────────────────────────────────────────┤
│  get_context     │  At session START — loads all active facts    │
│                  │  + recent memories for instant orientation     │
├──────────────────┼───────────────────────────────────────────────┤
│  memory_search   │  Before answering architecture/design Q's     │
│                  │  "What's our auth pattern again?"              │
├──────────────────┼───────────────────────────────────────────────┤
│  add_memory      │  After implementing features, fixing bugs,    │
│                  │  making architectural decisions                │
├──────────────────┼───────────────────────────────────────────────┤
│  add_fact        │  For atomic rules that never change:          │
│                  │  stack choices, team preferences, standards   │
└──────────────────┴───────────────────────────────────────────────┘

Suggested system prompt addition:

At the start of every session, call get_context to load my preferences and project context.
Before answering any technical question, call memory_search with the relevant topic.
After implementing features or making decisions, call add_memory to persist the context.

friday/
│
├── 📡 gateway/
│   └── main.py              # FastAPI backbone — auth, routing, all endpoints
│
├── 🧩 layers/               # Pluggable memory backends (swap any layer)
│   ├── layer2_mem0.py       # Semantic memory — Mem0 cloud API
│   ├── layer3_chroma.py     # Vector store — ChromaDB (local)
│   └── layer4_neo4j.py      # Knowledge graph — Neo4j
│
├── ⚡ pipelines/            # Background intelligence
│   ├── auto_graph.py        # LLM entity extraction → Neo4j wiring
│   └── extract_facts.py     # S3-style versioned fact management
│
├── 🔀 orchestrator/
│   └── router.py            # Query routing — picks best layer per query type
│
├── 🔌 mcp/
│   └── server.py            # MCP stdio server (JSON-RPC 2.0)
│                            # ← This is what your IDE connects to
│
├── 🎨 studio/
│   └── index.html           # Neural Studio — 1,400 lines, zero dependencies
│                            # force-graph + d3 + vanilla JS
│
├── 🐳 docker-compose.yml    # Neo4j + Friday Brain — production-ready
├── 🐳 Dockerfile            # python:3.11-slim, multi-stage ready
├── 📦 requirements.txt      # Pinned dependencies
└── 🌱 seed/                 # Demo data to bootstrap a fresh install
    ├── facts.example.json
    └── blueprints/demo_architecture.md

Data Flow:

[Your IDE] 
    → MCP call: add_memory("We use Redis for rate limiting")
        → gateway/main.py  → Mem0 store (sync)
                           → auto_graph.py (background)
                               → DeepSeek: extract entities
                               → Neo4j: MERGE Redis node
                               → Neo4j: CREATE edge (:App)-[:USES]->(:Redis)
        ← {"status": "added", "mem0_id": "abc123"}

All authenticated endpoints require the X-Brain-Key header.
🌐 = public endpoint (no auth required).

Full interactive docs: http://localhost/docs

Where to get your keys (all have free tiers):

v1.0 — Foundation ✅ shipped

• FastAPI memory gateway with full REST API
• Neo4j knowledge graph integration
• Autonomous graph extraction engine (DeepSeek + Neo4j)
• Neural Studio UI — Obsidian-grade graph browser
• MCP server — Cursor / Antigravity / Claude Desktop / VS Code
• S3-style versioned facts ledger
• Docker Compose — 1-command self-hosted setup
• ChromaDB semantic search layer
• Full CRUD via Neural Studio (add / rename / delete / connect)
• Per-project constellation namespacing

v1.1 — Multi-User & DX 🚧 in progress

• Multi-user support with isolated namespaces
• Python SDK (pip install friday-client)
• TypeScript/JavaScript SDK
• friday CLI — friday add "...", friday search "..." from terminal

v1.2 — Integrations 📋 planned

• GitHub Actions bot — auto-store PR summaries as memories
• Slack integration — /friday remember ... from Slack
• Jira / Linear sync — auto-import tickets as project context
• VS Code extension — sidebar memory panel

v2.0 — Cloud 🌐 future

• Friday Cloud — managed, zero-infra option
• Team workspaces — shared memory across your engineering team
• Private beta waitlist

Friday is built in public and we'd love your contributions.

# Fork & clone
git clone https://github.com/YOUR_USERNAME/friday.git
cd friday

# Set up environment
cp .env.example .env
pip install -r requirements.txt

# Run tests — all must be green before PRing
python -m pytest tests/ -v
# ✅ 9 passed in 0.34s

# Create your branch
git checkout -b feat/your-amazing-feature

# Commit using conventional commits
git commit -m "feat: add X that does Y"

# Push & open PR
git push origin feat/your-amazing-feature

See CONTRIBUTING.md for full guidelines.
Browse good first issue labels to find where to start.

Friday is designed for self-hosted deployment. A few notes:

• API Key auth — all write endpoints require X-Brain-Key header
• Public read — /health, /facts (read), /api/graph-data, and Neural Studio are public by default. If you expose Friday publicly, consider adding reverse-proxy authentication (e.g., Nginx basic auth or Cloudflare Access).
• Secrets — never commit your .env. It's in .gitignore by default.
• Network — by default, Friday binds to 0.0.0.0. For local-only use, change to 127.0.0.1 in .env.

Found a vulnerability? Please open a private security advisory on GitHub rather than a public issue.

MIT © 2026 Friday Contributors — see LICENSE for details.