Friday

Every developer deserves a F.R.I.D.A.Y.

The open-source, self-hosted persistent cognitive memory layer for AI coding agents.
Cursor forgets. Claude forgets. Copilot forgets.
Friday doesn't.

🚀 Quickstart

🔌 IDE Setup

✨ Features

📡 API Docs

🏗️ Architecture

🗺️ Roadmap

_{Live Neural Studio — Obsidian-grade knowledge graph visualizer mapping real AI cognitive memory constellations.}

🧠 The Problem — AI Amnesia

You're deep in a session with Cursor. You've explained your entire auth architecture.
Your JWT strategy. Your database schema. Your preferred patterns.

You open a new chat.

You:     "Add a refresh token endpoint using our JWT pattern."
Cursor:  "Sure! What JWT library are you using? And how is your auth structured?"
You:     😤  (again. for the 47th time this week.)

Every AI coding assistant suffers from the same critical design flaw: no persistent memory.

Each session starts at zero. Your AI gives you generic advice instead of deeply personalized,
project-specific insight. You're repeating yourself constantly.

The result? You're spending up to 40% of your time just rebuilding context — instead of building product.

💡 The Solution

Friday is a persistent cognitive memory backbone that plugs into your existing AI tools via the
Model Context Protocol (MCP). It runs fully self-hosted on your
own infrastructure — your data never leaves your machine or your server.

┌──────────────────────────────────────────────────────────────────────┐
│         YOUR AI AGENT   (Cursor / Claude / Antigravity / VS Code)    │
└──────────────────────────────┬───────────────────────────────────────┘
                               │
                    4 MCP Tools (stdio transport)
                    ├── add_memory
                    ├── add_fact
                    ├── memory_search
                    └── get_context
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────────┐
│                        FRIDAY BRAIN (FastAPI)                        │
│                                                                      │
│    Layer 2: Mem0           Layer 3: ChromaDB      Layer 4: Neo4j     │
│  ┌──────────────────┐    ┌─────────────────┐    ┌───────────────┐   │
│  │ Semantic Memory  │    │  Vector Search  │    │  Knowledge    │   │
│  │                  │    │                 │    │  Graph        │   │
│  │ • Cross-session  │    │ • 90% fewer     │    │  ──────────   │   │
│  │   persistence    │    │   tokens via    │    │  ● WebApp     │   │
│  │ • Contextual     │    │   targeted      │    │  ● Auth       │   │
│  │   similarity     │    │   retrieval     │    │  ● Payments   │   │
│  └──────────────────┘    └─────────────────┘    └───────────────┘   │
│                                                                      │
│    ⚡ Auto-Graph Engine                                              │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  Every memory → LLM extraction → Neo4j nodes + edges        │    │
│  │  Zero manual linking. Your knowledge base wires itself.      │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                      │
│    🎨 Neural Studio                                                  │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │  Obsidian-grade live knowledge graph browser                 │    │
│  │  Spread slider • Filters • Inspector drawer • Full CRUD      │    │
│  └─────────────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────────────┘

📊 Why Friday?

🚀 60-Second Quickstart

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/itskie/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. ✅

🔌 Connecting Your Agents (MCP Setup)

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.

Step-by-Step Client Configurations

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/.

✨ Features

⚡ Auto-Graph Engine — Zero Manual Linking

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.

🎨 Neural Studio — Live Knowledge Graph UI

A browser-based visual explorer for your AI's knowledge — built with the same graph engine
that powers Obsidian's graph view.

What you can do:

• 🌌 Explore your entire knowledge base as a living constellation
• 🔍 Full-text search — camera auto-follows, inspector slides open
• 🎛️ Spread slider (1–10) — breathe space into dense graphs in real-time
• 🏷️ Project filter chips — isolate WebApp vs Auth vs Payments constellations
• 🖱️ Click any node → right-side inspector with facts, edges, actions
• ➕ Add / ✏️ Rename / 🗑️ Delete / 🔗 Connect — full CRUD via UI
• ❄️ Freeze physics to lock a layout, Fit View to reset camera
• ⚡ Live auto-refresh as new memories arrive

📌 S3-Style Versioned Facts Ledger

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

🔍 Semantic Search — 90% Fewer Tokens

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

🔌 4 Native MCP Tools — Your AI Learns to Use Them

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.

🏗️ Architecture

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"}

📡 API Reference

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

Full interactive docs: http://localhost/docs

🔑 Environment Variables

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

🗺️ Roadmap

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

🤝 Contributing

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.

🔒 Security

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.

📄 License

MIT © 2026 Friday Contributors — see LICENSE for details.