Friday

 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 ✨ Features 📡 API Docs 🏗️ Architecture 🗺️ Roadmap

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

---

Problem: Session Amnesia & Token Overhead

Modern coding assistants (Cursor, Claude Code, Copilot, Antigravity) initialize each chat thread without cross-session memory. While developers frequently mitigate this using project documentation (AGENTS.md, prompt templates, or manual file references), this workflow presents two major bottlenecks:

1. Context Window & Token Inefficiency: Injecting massive architecture documents or having agents repeatedly read entire repository directories consumes thousands of context tokens on every single query.
2. Loss of Incremental Decisions: Ephemeral decisions—such as chosen dependency versions, schema adjustments, or bug fix rationale made in prior sessions—are lost when a session resets, forcing developers to repeatedly re-explain core constraints.

---

Architecture & Solution

Friday runs as an open-source, self-hosted Model Context Protocol (MCP) server. Instead of dumping entire documentation files into prompt context, Friday exposes 4 targeted tools (add_memory, add_fact, memory_search, get_context) backed by a multi-tier storage engine:

• Semantic Memory (Mem0): Preserves past decisions, preferences, and workflows across sessions.
• Targeted Vector Search (ChromaDB): Retrieves only the exact memory snippets relevant to the immediate query.
• Relational Knowledge Graph (Neo4j): Automatically extracts entities and relationships in the background, mapping connections between components, schemas, and dependencies.
• Neural Studio: Embedded web visualizer to inspect and query the knowledge graph in real time.

┌──────────────────────────────────────────────────────────────────────┐
│         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      │    │
│  └─────────────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────────────┘

---

Comparison: Static Prompts vs. Persistent Graph Memory

| Capability | Static Prompts / AGENTS.md | Friday (MCP + Neo4j + Vector) | | :--- | :---: | :---: | | Cross-Session Memory | ❌ Lost on thread reset | ✅ Persisted in database | | Context Retrieval | ⚠️ Brute-force re-reading entire files | ✅ Targeted semantic & graph queries | | Entity Relationships | ❌ Unstructured flat text | ✅ Neo4j Knowledge Graph | | Graph Generation | ❌ Manual maintenance | ✅ Autonomous background extraction | | Visual Inspection | ❌ None | ✅ Live browser UI (Neural Studio) | | Audit Trail | ❌ None | ✅ Immutable versioned facts ledger | | Infrastructure | Local files | 100% Self-hosted (Docker Compose) |

---

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

---

🔌 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:

⚡ Antigravity IDE

Add Friday to your Antigravity global MCP configuration at ~/.gemini/config/mcp_config.json:

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

(If Friday runs on a remote server/EC2, change FRIDAY_URL to http://:8000)

🤖 Claude Code (CLI)

Connect Claude Code to your Friday brain with one terminal command:

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

Or configure directly in ~/.claude.json under "mcpServers":

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

🖱️ Cursor

Create or edit .cursor/mcp.json in your project root (or add globally in Cursor Settings → MCP → Add New 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"
      }
    }
  }
}

(For a remote server, change FRIDAY_URL to http://:8000)

📟 Codex & Autonomous Agents (CLI / Scripts)

Any custom agent, Codex script, or CI loop can interact with Friday in two ways:

Option A: Via MCP stdio Run the MCP server directly as a subprocess using standard JSON-RPC 2.0.

Option B: Direct HTTP REST API (zero client dependencies)

# Store memory from any agent script
curl -X POST http://: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://:8000/search   -H "X-Brain-Key: your_key"   -H "Content-Type: application/json"   -d '{"query": "How is payments structured?", "project": "MyApp"}'

💻 VS Code (Cline / Roo Code)

Add to your VS Code settings.json (or via Cline MCP settings):

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

🖥️ Claude Desktop

Edit your Claude Desktop configuration:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "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/](examples/).

---

Features

Auto-Graph Engine — Automated Relationship Extraction

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 — Graph Visualization 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

---

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 via Vector Embeddings

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

---

Native MCP Toolset

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 clou

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [friday-memory](https://github.com/friday-memory)
- **Source:** [friday-memory/friday](https://github.com/friday-memory/friday)
- **License:** MIT
- **Homepage:** https://github.com/itskie/friday

Install and usage instructions live in the source repository linked above.