# Friday

> ⚡ The open-source persistent cognitive memory layer for AI coding agents. Stop your Cursor, Claude & Copilot from having amnesia.

- **Type:** MCP server
- **Install:** `agentstack add mcp-friday-memory-friday`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [friday-memory](https://agentstack.voostack.com/s/friday-memory)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [friday-memory](https://github.com/friday-memory)
- **Source:** https://github.com/friday-memory/friday
- **Website:** https://github.com/itskie/friday

## Install

```sh
agentstack add mcp-friday-memory-friday
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

 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](https://docker.com) + [Docker Compose](https://docs.docker.com/compose/) installed.  
> That's literally it. No Python setup. No database config. No services to manage manually.

**Clone and configure**
```bash
git clone https://github.com/friday-memory/friday.git
cd friday
cp .env.example .env
```

**Fill in your `.env`** — takes 60 seconds

```env
# 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**
```bash
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**
```bash
curl http://localhost/health
# {"status":"healthy","layers":{"neo4j":"ok","mem0":"ok","facts":"ok (0 entries)"}}
```

**Store your first memory**
```bash
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)](https://modelcontextprotocol.io).

```
 ┌───────────────────────┐
 │   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`:

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

```bash
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"`:

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

🖱️ Cursor

Create or edit `.cursor/mcp.json` in your project root (or add globally in **Cursor Settings → MCP → Add New Server**):

```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"
      }
    }
  }
}
```
*(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)
```bash
# 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):

```json
{
  "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`

```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](https://obsidian.md)'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.

```python
# 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.

```python
# 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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-friday-memory-friday
- Seller: https://agentstack.voostack.com/s/friday-memory
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.