Show HN：Friday——面向 AI 编程 Agent 的自托管持久记忆系统（MCP）

---

问题：会话失忆与 Token 开销

现代编程助手（Cursor、Claude Code、Copilot、Antigravity）在初始化每个聊天线程时，都不具备跨会话记忆。开发者虽然经常通过项目文档（AGENTS.md、提示词模板或手动引用文件）缓解这一问题，但这套工作流存在两项主要瓶颈：

1. 上下文窗口与 Token 效率问题：将大量架构文档注入提示词上下文，或让 Agent 反复读取整个仓库目录，会在每一次查询中消耗数千个上下文 token。
2. 增量决策丢失：此前会话中作出的临时决策——例如选定的依赖版本、Schema 调整或修复 Bug 的理由——会在会话重置后丢失，迫使开发者不断重新解释核心约束。

---

Friday 作为开源、自托管的 Model Context Protocol（MCP）服务器运行。它不将完整文档文件一股脑塞进提示词上下文，而是提供 4 个针对性工具（add_memory、add_fact、memory_search、get_context），并由多层存储引擎支撑：

• 语义记忆（Mem0）：跨会话保留过去的决策、偏好和工作流。

• 定向向量搜索（ChromaDB）：仅检索与当前查询直接相关的精确记忆片段。

• 关系型知识图谱（Neo4j）：在后台自动提取实体和关系，映射组件、Schema 与依赖项之间的连接。

• Neural Studio：内置 Web 可视化工具，可实时检查和查询知识图谱。

  ┌──────────────────────────────────────────────────────────────────────┐ │ 你的 AI AGENT（Cursor / Claude / Antigravity / VS Code） │ └──────────────────────────────┬───────────────────────────────────────┘ │ 4 个 MCP 工具（stdio 传输） ├── add_memory ├── add_fact ├── memory_search └── get_context │ ▼ ┌──────────────────────────────────────────────────────────────────────┐ │ FRIDAY BRAIN（FastAPI） │ │ │ │ 第 2 层：Mem0 第 3 层：ChromaDB 第 4 层：Neo4j │ │ ┌──────────────────┐ ┌─────────────────┐ ┌───────────────┐ │ │ │ 语义记忆 │ │ 向量搜索 │ │ 知识图谱 │ │ │ │ │ │ │ │ ────────── │ │ │ │ • 跨会话持久化 │ │ • 通过定向检索 │ │ ● WebApp │ │ │ │ • 上下文相似度 │ │ 减少 90% │ │ ● Auth │ │ │ │ │ │ token │ │ ● Payments │ │ │ └──────────────────┘ └─────────────────┘ └───────────────┘ │ │ │ │ ⚡ 自动图谱引擎 │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 每条记忆 → LLM 提取 → Neo4j 节点与边 │ │ │ │ 无需手动关联。你的知识库会自行建立连接。 │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ 🎨 Neural Studio │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 具备 Obsidian 水准的实时知识图谱浏览器 │ │ │ │ 扩散滑块 • 筛选器 • 检查器抽屉 • 完整 CRUD │ │ │ └─────────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────┘

---

对比：静态提示词与持久化图谱记忆

能力	静态提示词 / AGENTS.md	Friday（MCP + Neo4j + Vector）
跨会话记忆	❌ 在线程重置时丢失	✅ 持久化保存至数据库
上下文检索	⚠️ 暴力重新读取完整文件	✅ 定向语义与图谱查询
实体关系	❌ 无结构的扁平文本	✅ Neo4j 知识图谱
图谱生成	❌ 需要手动维护	✅ 自主后台提取
可视化检查	❌ 无	✅ 实时浏览器 UI（Neural Studio）
审计记录	❌ 无	✅ 不可变的版本化事实账本
基础设施	本地文件	100% 自托管（Docker Compose）

---

**要求：**已安装 Docker + Docker Compose。
就这些。无需配置 Python，无需配置数据库，也无需手动管理服务。

克隆并配置

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

填写你的 .env——只需 60 秒

# 设置你自己的主密码，以保护自托管服务器
FRIDAY_API_KEY=pick_any_secret_password_you_want

# DeepSeek（极具性价比——$0.14/百万 token）
# 在此获取：https://platform.deepseek.com
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Mem0——提供额度充足的免费层
# 在此获取：https://mem0.ai
MEM0_API_KEY=m0-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Neo4j 密码——由你自行设置
NEO4J_PASSWORD=change_to_something_strong

使用一条命令启动全部服务

这将启动：

• 🧠 http://localhost 上的 Friday Brain
• 🕸️ http://localhost:7474 上的 Neo4j
• 🎨 http://localhost 上的 Neural Studio

验证服务是否正在运行

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

存储你的第一条记忆

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

你的 AI 现在会永远记住。 ✅

---

🔌 连接你的 Agent（MCP 设置）

Friday 被设计为所有 AI 编程工具的中央认知记忆。
无论 Friday 是运行在你的本地机器上，还是运行在远程 24/7 云服务器（AWS EC2、VPS、Homelab）上，每个 Agent 都可通过 Model Context Protocol（MCP） 连接至同一份统一记忆。

 ┌───────────────────────┐
 │   Cursor（桌面端）    │──┐
 └───────────────────────┘  │
 ┌───────────────────────┐  │
 │    Claude Code CLI    │──┼── MCP 协议（stdio 传输）
 └───────────────────────┘  │   FRIDAY_URL="http://your-server-ip:8000"
 ┌───────────────────────┐  │   BRAIN_API_KEY="your_secret_key"
 │   Antigravity IDE     │──┤
 └───────────────────────┘  │
 ┌───────────────────────┐  │
 │ Codex / 自定义 Agent  │──┘
 └───────────────────────┘
                            ▼
             ┌──────────────────────────────┐
             │      FRIDAY 中央大脑          │
             │   （云端/EC2 自托管）         │
             │   FastAPI + Mem0 + Neo4j     │
             └──────────────────────────────┘

💡 共享大脑的超能力：你在终端中通过 Claude Code 存储的一条架构规则或决策，会立即供桌面端的 Cursor、Antigravity IDE 或 Codex 使用。无需手动同步。一颗大脑覆盖你的整个工具链。

---

分步客户端配置

从下方选择你的客户端，粘贴配置并重启 Agent：

⚡ Antigravity IDE

将 Friday 添加到 Antigravity 的全局 MCP 配置 ~/.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"
      }
    }
  }
}

(如果 Friday 运行在远程服务器/EC2 上，请将 FRIDAY_URL 改为 http://<your-server-ip>:8000)

🤖 Claude Code（CLI）

通过一条终端命令将 Claude Code 连接至你的 Friday 大脑：

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

或者直接在 ~/.claude.json 的 "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

在项目根目录创建或编辑 .cursor/mcp.json（或者在 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"
      }
    }
  }
}

(对于远程服务器，请将 FRIDAY_URL 改为 http://<your-server-ip>:8000)

📟 Codex 与自主 Agent（CLI / 脚本）

任何自定义 Agent、Codex 脚本或 CI 循环都可以通过两种方式与 Friday 交互：

方案 A：通过 MCP stdio：使用标准 JSON-RPC 2.0，直接将 MCP 服务器作为子进程运行。

方案 B：直接 HTTP REST API（无需客户端依赖）

# 从任意 Agent 脚本存储记忆
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"}'

# 在发起提示词前检索相关上下文
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"}'

💻 VS Code（Cline / Roo Code）

添加至你的 VS Code settings.json（或通过 Cline MCP 设置添加）：

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

编辑你的 Claude Desktop 配置：

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

📁 所有客户端的预构建配置模板均位于 examples/。

---

自动图谱引擎——自动化关系提取

你存储的每条记忆都会自动由 LLM（DeepSeek Flash）分析。
实体和关系会被提取并接入你的 Neo4j 知识图谱，
无需你进行任何手动操作。

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

自动提取的图谱：
  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

无需 YAML，无需手动打标签。只需存储记忆，你的知识图谱便会自行构建。

---

Neural Studio——图谱可视化 UI

这是一个基于浏览器的 AI 知识可视化浏览器，采用与 Obsidian 图谱视图相同的图引擎构建。

你可以完成的操作：

• 🌌 将整个知识库作为动态星座进行探索
• 🔍 全文搜索——镜头自动跟随，检查器自动滑出
• 🎛️ 扩散滑块（1–10）——实时为密集图谱腾出空间
• 🏷️ 项目筛选标签——隔离 WebApp、Auth 与 Payments 等星座
• 🖱️ 点击任意节点 → 右侧检查器显示事实、边和操作
• ➕ 添加 / ✏️ 重命名 / 🗑️ 删除 / 🔗 连接——通过 UI 完成完整 CRUD
• ❄️ 冻结物理布局以锁定图形，使用 适配视图重置镜头
• ⚡ 新记忆到达时实时自动刷新

---

离散事实（规则、偏好、常量）会以不可变版本历史保存。
旧版本会被标记为已替代，但绝不会删除。你始终拥有完整的审计记录。

# 存储一条事实
POST /facts  →  {"content": "We deploy on Ubuntu 22.04 LTS + systemd"}
# id: "a3f9e1b2", created_at: "2026-09-01", superseded: false

# 3 个月后——完成升级
POST /facts  →  {"content": "We deploy on Ubuntu 24.04 LTS + Docker Compose"}
# 旧事实：superseded: true  ← 为历史记录保留
# 新事实：superseded: false ←

---

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.

---

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)

---

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

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, changeFRIDAY_URL to http://<your-server-ip>: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, changeFRIDAY_URL to http://<your-server-ip>: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://<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"}'

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

---

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

---

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

---

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

Method	Endpoint	Auth	Description
GET	/ 🌐	—	Serves the Neural Studio UI
GET	/health 🌐	—	Health check — reports status of all layers
GET	/docs 🌐	—	Interactive Swagger UI
POST	/add	✅	Store a memory + trigger auto-graph wiring
POST	/facts	✅	Add or supersede a versioned fact
GET	/facts 🌐	—	List all active facts
GET	/facts?include_superseded=true 🌐	—	Full history including superseded
POST	/search	✅	Semantic search via Mem0
POST	/ingest	✅	Ingest a document / architecture blueprint
GET	/api/graph-data 🌐	—	All nodes + edges for Neural Studio
GET	/api/search-quick?q=term 🌐	—	Fast fuzzy node name search
POST	/api/node/create	✅	Create entity node in graph
DELETE	/api/node/{id}	✅	Delete node + all relationships
POST	/api/node/rename	✅	Rename an entity node
POST	/api/link/create	✅	Create a typed relationship edge

Full interactive docs: http://localhost/docs

---

Variable	Required	Default	Description
FRIDAY_API_KEY	✅	—	Your self-hosted server secret (set by you to protect endpoints)
DEEPSEEK_API_KEY	✅	—	LLM key for auto-graph extraction
MEM0_API_KEY	✅	—	Mem0 key for semantic memory
NEO4J_PASSWORD	✅	—	Neo4j DB password (you set this)
NEO4J_URI	—	bolt://neo4j:7687	Neo4j connection string
NEO4J_USER	—	neo4j	Neo4j username
DEEPSEEK_BASE_URL	—	https://api.deepseek.com	LLM API base URL
DEEPSEEK_MODEL	—	deepseek-chat	LLM model name
FACTS_PATH	—	/app/facts/facts.json	Path for facts ledger file
HOST	—	0.0.0.0	Server bind address
PORT	—	8000	Server port

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

Service	Link	Cost
DeepSeek	platform.deepseek.com	~$0.14/M tokens — cheapest capable LLM
Mem0	mem0.ai	Generous free tier
Neo4j	Bundled in Docker Compose	Free & local

---

v1.0 — Foundation ✅ shipped

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

v1.2 — Integrations 📋 planned

v2.0 — Cloud 🌐 future

---

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.

---

Built for the AI-native developer generation.

If Friday saved you from AI amnesia, please consider giving it a ⭐
It helps more developers discover the project and keeps us motivated.

⭐ Star on GitHub · 🐛 Report Bug · 💡 Request Feature · 💬 Discussions

Made with ❤️ by developers who were tired of repeating themselves to their AI.