> Source: https://www.esfis.com/en/docs · esfis, your projects, your context, your agents. Updated 17 September 2026.

# Docs

How esfis 1.8 works, from your first project to the command line. The app is still in early access: what follows is what it does today, and nothing it might do later.

## On this page

Guide

- [What esfis is](#introduction) · [The first five minutes](#start)

- [Projects](#projects) · [Agents](#agents)

- [Tasks](#tasks) · [Activity](#activity)

- [Context](#context) · [Memory](#memory)

- [Spaces and policies](#spaces)

- [Agent usage](#usage)

Reference

- [Connecting your AI](#mcp)

- [Terminal commands](#terminal)

- [Shortcuts](#shortcuts)

- [Local data](#local-data)

- [Supported agents](#supported-agents)

## What esfis is

esfis is a macOS app for working on your projects with the AI agents you already use. It is not a platform you have to move anything into: it runs on top of the folders, files and sessions that are already on your computer.

It has three parts:

ProjectsYour folders. Each one has its own activity, its own tasks and its own context space.
AgentsThe CLIs you already know — Claude Code, Codex, Copilot, Grok, Antigravity, Ollama — in real terminals.
ContextWhat the project has to remember, shared with every agent over MCP and stored on your Mac.

The window has four sections: **Home** (projects and activity), **Agents** (the terminals), **Memory** (the context) and **Settings**. The app, the `esfis` command line and the MCP server are all the same binary.

## The first five minutes

- **Add a folder**In Home, “Add a folder”. It becomes a project and gets its space.

- **Open an agent**In Agents, pick one. It opens in the folder, with your `PATH` and your keys.

- **Connect the context**In Settings, copy the command for your agent and hit Check.

- **Come back tomorrow**Home tells you where you left off and what each agent decided.

The command for Claude Code, which is the one most people need:

```
claude mcp add --scope user esfis -- ~/.esfis/bin/esfis --mcp
```

## Projects

A project is a folder. You add it from the app, and esfis neither moves it nor rearranges it. Everything that happens there — the agents you open, their sessions, the context they store — is tied to that folder.

### Every project, its own space

Adding the folder creates a space with its name and its path. An agent working inside it is already in the project: nobody has to tell it anything. If a space already contains that folder (a client space grouping several projects, say) or one already has that name, esfis leaves it alone; it only attaches the folder if the space had none.

From the terminal it is the same thing:

```
esfis --space-add project1 --path ~/Documents/Project1
```

## Agents

Each agent is the CLI you already use, in a real terminal inside esfis. It opens in the project folder with a *login shell* — the same `PATH` and the same keys as your own terminal — and talks to its provider exactly as it would outside esfis.

### Several at once

Split the window (`⌘D` to the right, `⇧⌘D` below), send the same prompt to every session (`⇧⌘B`), and switch projects without stopping the agents in the others.

### Models, sessions and providers

- Every pane has its own model menu, which switches the model using that CLI's own command (`/model`, or `/load` in Ollama) without closing the session.

- Changing section or closing the window stops no agent. Quitting esfis does, and it asks first.

- Providers you do not use can be switched off in Settings › Agents.

## Tasks

Next to each agent sits the project's Tasks panel, for noting what should not happen right now without losing your thread.

| Action | What happens |
| --- | --- |
| Click | Sends the task to the agent and presses Return. |
| ⌥ -click | Leaves it typed in the terminal, so you can look it over first. |
| Circle | Marks it done, or back to open. |

Every task remembers which agent you sent it to. The list is a Markdown file inside the project, at `.esfis/feina.md`, with one `- [ ]` line per task: you can edit it by hand, and it travels to any Mac that has the folder.

## Activity

Home has one row per project, from the one you touched most recently to the one you have left alone longest. It is there so you can get back to work without having to remember where you were.

Files and last changefrom the folder

Branch.git/HEAD

Open agentsright now

Context and decisionsfrom the space

Sessions and agentslast 30 days

Open tasks.esfis/feina.md

Latest decision and where you left offcontext + sessions

All of it is read from disk, in the background and without spawning subprocesses, from the logs Claude Code, Codex and Grok already leave behind. Folders like `node_modules` or `.build` are not counted.

## Context

A project's context is made of short items: decisions, instructions, goals, people, technologies. Each one remembers where it came from and when it was stored, and a new one can supersede an old one instead of sitting next to it.

### Who sees it

A project's context only reaches the agents working on that project. Personal context — which language you want answers in, say — reaches everywhere.

### How agents get to it

They read and write it over MCP. What is worth storing is decided by the agent; esfis only stores and retrieves, with no model call of its own. Every item carries the agent that stored it as its source, and the agent that receives it the next day can see that: “The API runs on PostgreSQL · Claude Code”. How to connect each agent is in [Connecting your AI](#mcp).

### Types

`identity`, `preference`, `person`, `project`, `goal`, `decision`, `technology`, `event`, `knowledge` and `instruction`. Every item also records who stored it and whether it was stated outright or inferred, and it can carry an expiry date.

## Memory

The Memory section shows you all the context and lets you correct it.

### List and Text

**List** is one row per item, with its type, where it came from and the buttons to change its type or forget it. **Text** is the whole context as running text:

```
## Standing instructions
[#3] Always answer in Catalan.

## Memories
[#12] The project is deployed on Vercel.
```

- Rewrite a line and you change that item.

- Delete it and it is forgotten: deactivated, and recoverable from the forgotten items.

- Add one without an `[#id]` and it is new.

- Nothing is stored until you press Save (`⌘S`), and if an agent wrote something in the meantime, it tells you first.

### Test and Conversation

These are two Settings tabs, next to [Spaces](#spaces). **Test** picks an AI and a space, asks it a question and shows what it would receive, with the score of each item and what stayed out. **Conversation** extracts context from a conversation you paste in, using the Anthropic API and your own key: it is the only feature that leaves the machine, and with MCP connected you do not need it.

### MEMORY.md

`~/.esfis/MEMORY.md` is the readable copy of your personal context (a space's context is not in there, because every project reads this file). Claude Code can read it without MCP if you add `@~/.esfis/MEMORY.md` to `~/.claude/CLAUDE.md`.

```
esfis --export            # refresh ~/.esfis/MEMORY.md
esfis --import-document   # take back whatever you edited in it
```

### Bringing in what you already have

The memory `.md` files assistants leave in `~/.claude/projects//memory/` can be imported. Running it again duplicates nothing, and an edited file replaces the old version.

```
esfis --import                       # ~/.claude/projects
esfis --import ~/notes ~/other/mem   # or whichever folders you name
```

## Spaces and policies

Spaces keep each project's or client's context apart. Policies say which AI sees which space. And the trace explains, afterwards, what each AI received and why.

### Spaces

An item with no space is personal and goes everywhere. An item with a space only ever surfaces inside it, and the space is checked before anything is searched: a perfect match belonging to another client is never even scored. An agent's space comes from the folder it works in (the longest path containing it); `ESFIS_SPACE` pins it.

```
esfis --spaces
esfis --space-add acme --kind client --path ~/Clients/acme
esfis --move 184 acme
esfis --add "Acme pays on 60-day terms." --space acme --until 2026-12-31
```

### Policies

The most specific rule wins: this AI in this space, this AI everywhere, everyone in this space, everyone. With no rule, access is allowed. An agent that cannot see a space cannot write to it or forget anything in it either.

In Settings › Spaces you choose, for every space and every AI, “Has access”, “No” or whatever the general rule says. From the terminal it is the same thing:

```
esfis --deny chatgpt acme
esfis --deny '*' acme
esfis --allow claude-code acme
esfis --policy
```

### Why it saw what it saw

Every `recall` over MCP leaves a delivery behind: what went in, what stayed out and why. Identifiers and reasons are stored, not the text. Of what another space or a policy kept out, the items that would have answered the question are named and the rest are counted. Deliveries are also in Settings › Spaces: click one and out comes the explanation.

```
esfis --deliveries
esfis --why 212
esfis --preview "which datastore do we use" --as codex --space esfis
```

### CLAUDE.md and AGENTS.md

`--compile` writes the current context inside a marked block (`` … ``) and touches nothing outside it. Compiling again with no changes does not change a single byte.

- **What goes in:** instructions, identity, preferences, projects, goals, decisions and technologies.

- **Only if** they are active, current, stated outright and permitted for that assistant.

- **Personal context** only with `--with-personal`, because these files end up in git.

```
esfis --compile agents --space esfis
esfis --compile claude --print
esfis --import-instructions CLAUDE.md   # the way back
```

### esfis and CLAUDE.md

esfis does not replace CLAUDE.md or Claude Code's Auto Memory: CLAUDE.md can be an output of esfis rather than its source. The difference is where the context lives and who is allowed to read it.

| | CLAUDE.md and Auto Memory | Context in esfis |
| --- | --- | --- |
| Format | Markdown text, in layers: organisation, user, project and subfolders | Items with a type, a space and metadata |
| Who reads it | Claude Code | Any agent over MCP, plus compiled CLAUDE.md or AGENTS.md |
| Who writes it | You, and Claude with Auto Memory | You and any connected agent |
| Provenance | Not recorded for each statement | Who, when, and whether it was stated or inferred |
| Currency | Until somebody edits or deletes it | An expiry date per item, and history |
| Permissions | None per item or per agent | Policies per agent and per space |
| Trace | Which files were loaded | Which items each agent received, and why |

Compared with Claude Code as of September 2026.

## Agent usage

The bar at the bottom of the Agents section, and its usage panel, show how much each agent has used, today and over the last few days, and how the machine is doing: CPU, memory and the hungriest processes. It is all read from the logs each CLI already writes locally, with no API calls at all.

```
esfis --usage --days 14     # the usage panel, as text
esfis --claude-bridge       # Claude's real limits (--remove takes it out)
```

Costs are an estimate based on public prices, which you can adjust in `~/.config/agent-orchestrator/pricing.json`.

## Connecting your AI

Settings › Connect your AI has what to copy for each client, and a Check button. esfis never writes another program's configuration for it.

| Client | How |
| --- | --- |
| Claude Code | claude mcp add --scope user esfis -- ~/.esfis/bin/esfis --mcp |
| Codex | codex mcp add esfis -- ~/.esfis/bin/esfis --mcp |
| Cursor | The JSON block below, in ~/.cursor/mcp.json |
| Gemini CLI | The JSON block below, in ~/.gemini/settings.json |
| Any chat | Instructions to paste, plus the context for each question from Test |

The generic form, for any other MCP client:

```
{ "mcpServers": { "esfis": { "command": "/Users/<you>/.esfis/bin/esfis", "args": ["--mcp"] } } }
```

### The tools

| Tool | What it does |
| --- | --- |
| recall | Returns the standing instructions and the context relevant to a question. |
| remember | Stores an item. Takes type , space , valid_until and supersedes , so a new item can replace an old one instead of piling up contradictions. |
| forget | Deactivates an item by id. It stays on as history. |
| memories | Lists what the agent can see in the space it is in. |

## Terminal commands

Everything the app does can be done from the terminal. `esfis --help` has them all; they exit 0 on success and 1 on failure.

| Command | What it does |
| --- | --- |
| --recall "…" | What esfis knows about this ( --as , --space ) |
| --preview "…" --as codex | What that AI would receive, and what would stay out |
| --why | Why an AI saw what it saw |
| --add "…" | Store context ( --type , --space , --until ) |
| --spaces · --space-add · --move | Spaces and what is in them |
| --policy · --allow · --deny | Who sees what |
| --compile claude\|agents | Write the context into CLAUDE.md or AGENTS.md |
| --import [folders] | Bring in the assistants' memory .md files |
| --list | Every item, forgotten ones included |
| --usage [--days N] | Agent usage |
| --doctor | Check that everything is where it should be |

`esfis --doctor` runs one check per line: the database, the schema, the vectors, whether the binary is the one the MCP configuration points at, whether `MEMORY.md` is up to date and whether there are duplicates. The same report is in Settings.

## Shortcuts

| Shortcut | What it does |
| --- | --- |
| ⌃⌘1 … ⌃⌘4 | Home, Agents, Memory, Settings |
| ⌘1 … ⌘9 | Jump to an agent pane |
| ⌘D · ⇧⌘D | Split right · split below |
| ⌘↩ | Zoom the pane (and back) |
| ⌥⌘ + arrows | Move focus between panes |
| ⇧⌘W | Close the pane |
| ⇧⌘B | Send the same prompt to every session |
| ⌃⌥⌘← · ⌃⌥⌘→ · ⌃⌥⌘↑ | Park the window on one side · fill the screen |
| ⌃⌘F | Full screen |
| ⌘S | Save the Memory text |
| ⇧⌘E | Refresh MEMORY.md |
| ⌘, | Settings |

## Local data

Everything is stored on your Mac. The MCP server speaks over standard input and opens no ports, and no account is needed.

| File | What is in it |
| --- | --- |
| ~/.esfis/memory.db | The context (SQLite): items, spaces, policies and history |
| ~/.esfis/MEMORY.md | The readable copy of your personal context |
| ~/.esfis/log.jsonl | One line per change |
| ~/.esfis/mcp.log | The MCP trace, only with ESFIS_LOG=1 |
| ~/.esfis/bin/esfis | The binary the agents call |
| /.esfis/feina.md | The project's tasks |

To show activity and usage, esfis reads files the CLIs already leave on disk, such as `~/.claude/projects` or `~/.codex/sessions`, and sends them nowhere.

## Supported agents

| Agent | What it is |
| --- | --- |
| Claude Code | Anthropic's terminal agent. Reads and writes context over MCP. |
| Codex | OpenAI's terminal agent. Reads and writes context over MCP. |
| Copilot | GitHub's terminal agent. |
| Grok | xAI's terminal agent. |
| Antigravity | Google's terminal agent ( agy ). Off by default; switch it on in Settings › Agents. |
| Ollama | Local models, running on your own machine. |

Any other MCP client can read and write the context too, Cursor and Gemini CLI among them.

## In development

esfis is at an early stage. Some features may change or disappear, and these pages are updated when they do. What has shipped is in the [changelog](https://www.esfis.com/en/changelog).

[Request early access](https://www.esfis.com/en/early-access)