# Empirical

> Empirical is one persistent memory layer for every AI you use. It stores project context, preferences, decisions, and durable notes as a queryable memory graph, then serves that graph to ChatGPT, Claude (web, Desktop, Claude Code), Codex, Copilot, Cursor, and Windsurf through MCP tools and a CLI. Save context once in one tool and every other connected tool can recall it.

- MCP endpoint (Streamable HTTP with OAuth): https://empirical.gauzza.com/mcp
- Install: npm install -g @empirical-gauzza/cli && empirical install
- Machine-readable docs: append /index.md to any docs URL, or fetch https://empirical.gauzza.com/llms-full.txt
- Blog feeds: https://empirical.gauzza.com/rss.xml (RSS 2.0) and https://empirical.gauzza.com/atom.xml (Atom)

## Docs

- [Overview](https://empirical.gauzza.com/docs/overview): What Empirical is, how memory flows across tools, and where to start.
- [Install CLI](https://empirical.gauzza.com/docs/install): Install Empirical CLI, configure local coding clients, and bootstrap headless OAuth tokens.
- [Your First Memory](https://empirical.gauzza.com/docs/first-memory): Capture your first durable memory and verify recall in one minute.
- [Concepts](https://empirical.gauzza.com/docs/concepts): Core concepts: scopes, relevance ranking, durable notes, and recall behavior.
- [Workspaces](https://empirical.gauzza.com/docs/workspaces): Connect ChatGPT, Claude or the CLI to a workspace, and switch between workspaces from any of them.
- [Claude Code](https://empirical.gauzza.com/docs/claude-code): Install and validate Empirical MCP inside Claude Code.
- [Cursor](https://empirical.gauzza.com/docs/cursor): Connect Cursor to Empirical memory with manual MCP configuration.
- [Windsurf](https://empirical.gauzza.com/docs/windsurf): Configure Windsurf MCP manually for Empirical and verify live recall.
- [Claude Desktop](https://empirical.gauzza.com/docs/claude-desktop): Configure Claude Desktop to use Empirical MCP over OAuth.
- [ChatGPT](https://empirical.gauzza.com/docs/chatgpt): Connect hosted /mcp endpoint to ChatGPT and complete OAuth.
- [MCP in Claude](https://empirical.gauzza.com/docs/mcp-claude): Choose the right Empirical MCP setup for Claude Code, Claude Desktop, or Claude on the web.
- [MCP in Codex](https://empirical.gauzza.com/docs/mcp-codex): Install the Empirical CLI, register the hosted MCP server in Codex, authenticate, and verify a tool call.
- [MCP in Copilot](https://empirical.gauzza.com/docs/mcp-copilot): Install Empirical into Copilot’s MCP configuration, complete OAuth, and verify memory recall.
- [Bring Obsidian notes into Empirical](https://empirical.gauzza.com/docs/obsidian): Manually curate durable Obsidian notes into Empirical; there is no live vault connector.
- [Bring Logseq notes into Empirical](https://empirical.gauzza.com/docs/logseq): Manually curate durable Logseq notes into Empirical; there is no live graph sync.
- [Bring Markdown notes into Empirical](https://empirical.gauzza.com/docs/markdown): Turn selected Markdown files into durable Empirical memories without importing every file.
- [Empirical Tokens](https://empirical.gauzza.com/docs/empirical-tokens): The monthly allowance for AI-heavy features like Writing Voice: what uses them, the reset, and how to check what is left.
- [Writing Voice](https://empirical.gauzza.com/docs/writing-voice): Build a reusable writing voice for your AI assistants from a guided interview, then install it as memories any agent can use.
- [Bring Notion notes into Empirical](https://empirical.gauzza.com/docs/notion): Manually export and curate useful Notion pages; there is no live Notion sync.
- [CLI Details](https://empirical.gauzza.com/docs/cli-details): Index of every CLI command family with links to memory, OAuth, workspace, Skills Kit, plugin, and diagnostic deep dives.
- [empirical doc](https://empirical.gauzza.com/docs/cli-doc-command): Progressive disclosure: list topics or print agent-readable instructions for any topic.
- [empirical kit](https://empirical.gauzza.com/docs/cli-kit): Create, source, activate, sync, and inspect reusable Skills Kits across coding agents.
- [empirical skill](https://empirical.gauzza.com/docs/cli-skill): List installed Skills, push authored SKILL.md files into Kits, inspect versions, and roll them back.
- [CLI-direct integration](https://empirical.gauzza.com/docs/cli-direct-mode): Use Empirical memory commands without MCP, from any shell environment.
- [Webhooks](https://empirical.gauzza.com/docs/webhooks): Send a workspace's item and note events to your app as signed JSON: setup, events, signature check, retries, and loop prevention.
- [Native Empirical plugin](https://empirical.gauzza.com/docs/cli-agent-skills): Install the native Empirical plugin so supported coding agents discover Empirical without competing side-loaded Skill files.
- [Memory commands](https://empirical.gauzza.com/docs/cli-memory): Understand why Empirical memory exists and how to query, write, maintain, and export it from the CLI.
- [Workspace commands](https://empirical.gauzza.com/docs/cli-workspaces): Understand workspace boundaries, project and team use cases, switching context, invites, and safe deletion.
- [CLI authentication](https://empirical.gauzza.com/docs/cli-auth): Choose interactive browser login or headless authentication for automation and containers.
- [OAuth commands](https://empirical.gauzza.com/docs/cli-oauth): Detailed browser, headless, Docker, and advanced client-credential OAuth flows.
- [Plugin commands](https://empirical.gauzza.com/docs/cli-plugins): Install and diagnose native Empirical plugins for supported coding agents.
- [Policy commands](https://empirical.gauzza.com/docs/cli-policy): Inspect and control local agent behavior around memory use and discretionary writes.
- [Device commands](https://empirical.gauzza.com/docs/cli-devices): Inspect registered agent devices and the Skills Kits they resolve.
- [Doctor and update](https://empirical.gauzza.com/docs/cli-doctor): Diagnose CLI authentication, connectivity, workspace, plugin, and version problems.
- [Empirical Memory plugin](https://empirical.gauzza.com/docs/plugin-empirical-memory): The required core plugin: native memory guidance and the Empirical MCP connection.
- [Work History plugin](https://empirical.gauzza.com/docs/plugin-work-history): Optional project history capture for concise completed-work summaries.
- [Scar Tissue plugin](https://empirical.gauzza.com/docs/plugin-scar-tissue): Optional prevention guidance for recurring failures and sharp edges.
- [Todo plugin](https://empirical.gauzza.com/docs/plugin-todo): Optional project-based todo tracking with status, next actions, and completion evidence.
- [REST API](https://empirical.gauzza.com/docs/rest-api): REST endpoints for memory operations and service integrations.
- [MCP tool reference](https://empirical.gauzza.com/docs/mcp-tools): Reference the Empirical MCP functions for memory, relationships, workspaces, and agent self-discovery.
- [MCP Server](https://empirical.gauzza.com/docs/mcp-server): MCP architecture, tool surface, auth modes, and deployment guidance.
- [Headless & CI](https://empirical.gauzza.com/docs/headless-ci): Production runbook for token refresh, secret storage, and CI safety checks.
- [Self-hosting](https://empirical.gauzza.com/docs/self-hosting): Run Empirical infrastructure in your own environment with OAuth and MCP enabled.
- [Security Model](https://empirical.gauzza.com/docs/security-model): Security boundaries, OAuth credential handling, and audit posture.
- [Data Export](https://empirical.gauzza.com/docs/data-export): Export and portability guidance for memory records and operational continuity.
- [Bot Setup](https://empirical.gauzza.com/docs/bot-setup): Production bot runtime setup with OAuth credentials, token refresh, and troubleshooting.
- [OAuth Connector Setup](https://empirical.gauzza.com/docs/oauth-tool-setup): Field-by-field connector settings for tools that integrate to Empirical MCP over OAuth.
- [Claude Web App Install](https://empirical.gauzza.com/docs/claude-web-app-install): Interactive setup flow for connecting Claude web app to your Empirical MCP endpoint.

## Blog

- [Empirical Blog](https://empirical.gauzza.com/blog): product updates and build notes
- [We beat Mem0 on their own benchmark, on their own terms. Now we can't submit it.](https://empirical.gauzza.com/blog/dolphinbench-full-hermes-run-we-beat-mem0-on-their-own-benchmark-now-we-cant-submit-it): Empirical scored 451 of 600 on Mem0's DolphinBench with the official Hermes agent, ahead of every published Hermes row. The full story of thirteen runs, an Azure credit that ran out mid-run, a packager that cannot hold a real Hermes run, and how to verify the result.
- [Everything we shipped in October](https://empirical.gauzza.com/blog/october-2026-changelog-everything-we-shipped-in-october): The October 2026 Empirical changelog. Writing Voice, Empirical Tokens, workspaces with a shape and a board, file attachments on memories, Daydream video talks, the approved Claude plugin, an updated ChatGPT app, and the CLI.
- [You told your agent about the lead. Then you typed it into the CRM again.](https://empirical.gauzza.com/blog/you-already-told-your-agent-a-board-built-from-what-you-already-said): Workspaces turn what you already tell an AI into a CRM, a todo list and a work tracker. What one sentence becomes, why the classifier can decline to guess a stage, and what it costs.
- [The decision was in memory. The contract was in Slack.](https://empirical.gauzza.com/blog/files-on-a-memory-files-live-with-the-decision-they-belong-to): Memories in Empirical can now hold files. Attach from the terminal, the portal, or an agent; delete is reversible for thirty days with a real purge date. What it does, what agents cannot do, and where it is not the right tool.
- [An AI agent that learns from you is great. Who owns what it learns?](https://empirical.gauzza.com/blog/who-owns-your-ai-context-who-owns-the-context-your-ai-builds): Agents like Hermes learn skills from how you use them. That makes the context they collect more valuable, and the question of who holds it more important. Three places AI context can live, a portability test you can run today, and what changes when you own the layer.
- [Anthropic published four weeks of optimization research. We turned it into a memory an agent could build on.](https://empirical.gauzza.com/blog/provenance-over-specificity-reran-anthropic-experiment-agent-with-memory-won): Anthropic had Claude optimize 30+ open-source biology models over four weeks. We gave an agent access to Anthropic's own published notes through Empirical and compared it against an agent with none. Seven of eight proposals traced to a real Anthropic source, and the agent found one optimization that appears in no source at all.
- [Memory that comes back to you: reminders in Empirical](https://empirical.gauzza.com/blog/reminders-reminders-memory-that-comes-back): Empirical memories can now carry a due date. Set one from ChatGPT, Claude, the CLI, or the portal, get a calendar entry with an alarm right away, and when it is due the reminder reaches your agents, your inbox, and the portal. How it works, with real screenshots and the design decisions behind it.
- [Blueprints now interview you before they install anything](https://empirical.gauzza.com/blog/guided-blueprints-guided-interview-blueprints): Empirical blueprints now run a branching guided interview and turn your answers into atomic memories linked to the blueprint's rules. A real walkthrough with live screenshots, what actually lands in your workspace, and how a connected assistant uses it.
- [Multi-agent workflows have an amnesia problem](https://empirical.gauzza.com/blog/multi-agent-amnesia-multi-agent-workflows-amnesia-problem): Multi-agent AI pipelines lose context at every handoff between agents. A look at why, backed by Salesforce's CRMArena-Pro benchmark, and what a shared memory layer actually fixes.
- [The Empirical CLI is becoming the front door](https://empirical.gauzza.com/blog/empirical-cli-front-door-empirical-cli-front-door): Empirical's CLI now provides a clearer path to OAuth, native plugin installation, and updates across Codex, Claude, and Copilot.
- [Empirical became a set of tools, not just one plugin](https://empirical.gauzza.com/blog/empirical-plugin-system-empirical-plugin-system): Empirical now installs as a core memory plugin with optional Work History, Scar Tissue, and Todo plugins for different ways of working with AI agents.
- [A Todo list that understands the project behind it](https://empirical.gauzza.com/blog/empirical-todo-skill-empirical-todo-skill): Empirical's optional Todo skill tracks actionable follow-ups by project, with examples for software, reading, and personal goals.
- [Memory trust and portability are live — error codes, receipts, duplicates, and export](https://empirical.gauzza.com/blog/memory-trust-and-portability-memory-trust-and-portability-release): Empirical ships MCP error codes with suggested fixes, save receipts, retrieval diagnostics, duplicate detection and merge, portable JSON export, and new workspace create/soft-delete tools.
- [Your AI needs your second brain](https://empirical.gauzza.com/blog/your-ai-needs-your-second-brain-ai-memory-layer-for-your-second-brain): Why second-brain users are the exact people who need a portable AI memory layer, and how Empirical turns saved notes into reusable context across tools.
- [Your vibe-coded app got serious faster than expected](https://empirical.gauzza.com/blog/vibe-coded-app-memory-vibe-coded-app-got-serious-faster-than-i-expected): A practical essay on how vibe-coded apps turn into real software before their builders have somewhere durable to keep launch warnings, assumptions, and scars.
- [Your AI coding agent needs scar tissue.](https://empirical.gauzza.com/blog/ai-coding-agent-scar-tissue-your-ai-coding-agent-needs-scar-tissue): AI coding agents become trustworthy when they retain remembered failure, not just prompt context.
- [Have you seen this ChatGPT warning before? Here’s a fix.](https://empirical.gauzza.com/blog/chatgpt-long-conversation-memory-chatgpt-forgets-details-in-long-conversations): A field note about what happened when a months-long ChatGPT health-tracking conversation started forgetting details, and how Empirical gave the record somewhere durable to live.
- [Empirical saved my ass.](https://empirical.gauzza.com/blog/empirical-ui-recovery-memory-recall-lost-ui-rework-recovered-with-empirical-memory): First-person incident report on recovering lost frontend work by querying Empirical memory, locating an unreachable WIP commit, and restoring the missing public-site redesign. Empirical saved my ass.
- [Audit every memory recall before it shapes output](https://empirical.gauzza.com/blog/audit-every-recall-logs-audit-every-memory-recall): Recall auditing in Empirical provides visibility into injected context, improving trust, safety, and debugging.
- [Build on the Empirical memory API in minutes](https://empirical.gauzza.com/blog/developer-grade-memory-api-build-on-the-empirical-memory-api): Empirical exposes memory through MCP, REST, and TypeScript interfaces so teams can integrate durable context into agents quickly.
- [Portable memory with no vendor lock-in](https://empirical.gauzza.com/blog/portable-memory-no-lockin-portable-memory-no-vendor-lock-in): Empirical keeps memory portable through exportable formats and open integration paths, preventing model or vendor lock-in.
- [Keep work and personal memory separate with scoped memory](https://empirical.gauzza.com/blog/scoped-memory-workspaces-keep-work-and-personal-memory-separate): Scoped memory in Empirical separates work and personal context, reducing leakage and improving relevance in AI responses.
- [Time-aware memory relevance for changing work](https://empirical.gauzza.com/blog/time-aware-memory-ranking-time-aware-memory-relevance): Empirical uses time-aware ranking to prioritize recent, relevant context and reduce stale memory interference.
- [Universal recall across every tool you use](https://empirical.gauzza.com/blog/universal-recall-memory-layer-universal-recall-across-tools): Universal recall in Empirical lets multiple AI tools query the same memory graph so context follows your work across surfaces.
- [Your coding agent is burning context you will never get back](https://empirical.gauzza.com/blog/coding-agent-context-savings-coding-agent-context-savings-22-45-percent): Real session telemetry showing 22-45% context reduction when replacing static AGENTS.md and CLAUDE.md files with on-demand Empirical memory queries. Measured across 10 real coding tasks and 1,978 Copilot CLI sessions.
- [How I Used Codex + Empirical to Lock In My Writing Voice](https://empirical.gauzza.com/blog/codex-session-tone-voice-how-i-used-codex-empirical-to-lock-in-my-writing-voice): April 30 note on using Empirical with Codex to define a repeatable writing voice through guided questions and live revision.
- [Workspace implementation is live: cleaner team memory, fewer context collisions](https://empirical.gauzza.com/blog/workspace-implementation-workspace-implementation-live): Empirical workspace release update covering team-scoped memory, cleaner join flows, and faster handoffs.
- [Discord bot implementation lessons: reliability first, features second](https://empirical.gauzza.com/blog/discord-bot-implementation-discord-bot-implementation-lessons): Empirical Discord bot retrospective on join flow issues, notification control, and reliability-driven workspace decisions.
- [CLI install updates: Q&A onboarding with dynamic global prompt building](https://empirical.gauzza.com/blog/cli-qa-global-prompt-cli-install-qa-dynamic-global-prompt): Empirical CLI onboarding update with Q&A flow and dynamic global prompt generation for consistent memory behavior.
- [Expanding full CLI tools alongside MCP integrations](https://empirical.gauzza.com/blog/full-cli-tools-expanded-full-cli-tools): Empirical update on expanded CLI command surface as a direct interface alongside MCP integrations.
- [100 users reached: signal and what comes next](https://empirical.gauzza.com/blog/100-users-100-users-milestone): Empirical milestone reflection after reaching 100 users and learning what users value most.
- [Installing Empirical in Claude web app: docs that remove setup guesswork](https://empirical.gauzza.com/blog/claude-web-install-docs-claude-web-install-docs): Empirical launch update for Claude web app installation docs with clearer MCP setup and troubleshooting guidance.
- [Submitting Empirical to the ChatGPT app ecosystem](https://empirical.gauzza.com/blog/chatgpt-app-submission-chatgpt-app-store-submission): Empirical update on ChatGPT app submission and the reliability work required for app review.
- [HIPAA-aligned storage and auditing improvements](https://empirical.gauzza.com/blog/hipaa-auditing-hipaa-compliant-storage-auditing): Empirical compliance update with HIPAA-aligned storage, auditing, and production safeguards.
- [Blueprint concept: portable skills across AI tools](https://empirical.gauzza.com/blog/blueprint-concept-blueprint-concept-what-it-solves): Empirical blueprint concept and how it enables portable skills across chat tools and coding agents.
- [Geocoding and image processing: richer memory with location context](https://empirical.gauzza.com/blog/geocoding-image-processing-geocoding-image-processing-location-search): Empirical feature update introducing geocoding, image processing, and location-aware memory search.
- [Why Empirical exists: context that survives tool switching](https://empirical.gauzza.com/blog/origin-story-why-empirical-exists): The Empirical origin story and mission to preserve long-term, portable memory across AI tools.