FI-Memory

# FIMemory

**A local store your AI tools can read, once connected and told to.**

FIMemory (FI Memory, by Future Industries) keeps your notes on your own
computer, and connects your AI tools to them so you stop re-explaining the
same project every session. The store is an ordinary folder of your own files:
no proprietary format, no server, no account, nothing uploaded anywhere.
New stores are **encrypted at rest by default**. You choose a passphrase, a
24-word recovery phrase prints once, and the files stay private wherever they
travel: a git host, a cloud backup, a USB stick. Prefer files you can open in
a text editor directly? Plaintext is one explicit choice away at setup, and an
encrypted store exports back to readable Markdown any time, gated by nothing
but your key.

## Start here

Two commands.

```
npm i -g fimemory
fimemory setup
```

If that first command fails with `EACCES: permission denied` (common on macOS,
where npm's default global folder is root-owned), give npm a folder you own and
retry. No sudo needed:

```
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
npm i -g fimemory
```

Then close and reopen any AI tool that was already running, because they read
their settings when they start.

That is the whole install. `setup` creates the store if you do not have one,
connects every AI tool it finds on this machine, then checks its own work and
prints what landed and what did not. Running it again is safe and boring:
everything already in place reports `unchanged` and nothing is rewritten. When
you are not sure whether it worked, run it again.

Creating a store on a terminal, `setup` walks you through encryption: you
choose a passphrase (or press one key to opt out with `--plaintext`), it
prints your 24-word recovery phrase once and asks you to prove you wrote it
down, then leaves the store unlocked on this machine for about 8 hours. In a
script or CI there is no prompt: pass `--passphrase "..."`, set
`GESTALT_PASSPHRASE`, or say `--plaintext`. With none of those it refuses
cleanly rather than guessing. Lose both the passphrase and the 24-word phrase
and the data is gone, by design; that is what "your key, not our servers"
costs, and the guided run will not let it happen silently.

One step `setup` cannot finish for you is Claude Code, which manages its own
config file. `setup` checks whether the `claude` command exists on this
machine: if it does, it prints a single `claude mcp add` line for you to
paste. If it does not (the VSCode extension and the desktop app install no
command line), it prints the exact JSON block and the file to put it in
instead. Either way it lands under Next steps rather than scrolling past.

If a step fails, the run keeps going and the failure gets its own line. Fix that
line, run `fimemory setup` again, and the steps that already worked stay put.

Three commands you will want later:

- `fimemory onboard` is the guided first step AFTER setup: it walks you
  through approving your first suggested edit, asks three questions about how
  you work and writes the answers into the store, then shows a search
  answering with your own facts. A wired store that holds nothing about you
  feels broken even when nothing is; this is the shortest way past that.
- `fimemory doctor` reads the whole setup back and tells you in plain words
  what is missing and what to do about it. A half-finished install is the most
  common way this goes wrong.
- `fimemory setup --plaintext` does the same install with an UNENCRYPTED
  store: every file readable in a text editor, by you and by any person or
  program with access to the folder. It is a real choice, stated plainly, not
  a hidden downgrade. A store that started plaintext can adopt encryption
  later with `fimemory encrypt` (cheapest before real content accumulates).

Before, a working install and a dead one looked identical. Now the install tells
you which one you have.

## Honest expectations

- **Installed and used by a person on Windows, macOS and Linux.** Not a runner
  claim: these are hand installs on real machines that then did real work, with
  two different AI tools reading and writing one store daily for months. The
  Windows box and the Mac each run Claude Code and Grok against it; the Linux
  box runs it headless. CI additionally builds, typechecks, tests, and
  global-installs the packed package on Linux and macOS runners every push.
  What that still does not cover is the long tail of host apps: a runner has no
  desktop session, so for any client other than the ones named below we have not
  watched the config `setup` wrote actually get loaded. On Linux the clipboard
  commands need `xclip`, or `wl-clipboard` on Wayland, and neither is installed
  by default. Run `fimemory doctor` if something looks wrong, and please report
  it.
- **It isn't cheaper than not remembering.** It's correct for a small
  premium, and far cheaper than pasting everything.
- **Agents read it when connected and told to.** `setup` writes the MCP
  config, the rule text and the retrieval hook for you, but no memory product
  can force a host to consult it unprompted on every turn.
- **Automated Sync is not shipped.** Multi-machine works via your own git remote,
  under your own account. No Sync service exists yet, so nothing you write
  ever leaves your machine unless you configure a remote yourself.
- **The shipped scope is your machines, several agents.** Point two machines at
  one private git remote: `fimemory join <url>` on the second machine, then
  `fimemory pull` before and after sessions. Edits to the same note never
  silently merge; the losing side becomes a pending proposal for you to review.
  Team features beyond your own remote are not in it.

## What `setup` actually runs

Five steps, in this order:

1. `init`, only when there is no store at `~/.fimemory` (an existing
   `~/.gestalt` from an earlier install is detected and kept). Skipped, never
   overwritten, when one is already there.
2. `install-mcp`, which writes the MCP server entry into each host config file
   it finds. This is what gives an assistant the ability to read the store.
3. `install-hooks`, which writes Claude Code's retrieval hook into
   `~/.claude/settings.json`. Skipped when `~/.claude` does not exist.
4. `install-rules`, which writes the memory rule block into each host's rules
   file. This is what makes an assistant actually use the store.
5. `doctor`, which reads all of it back and reports.

Hooks run before rules on purpose. The `shim` rule text tells the model that
relevant notes may already be in the turn, injected by the retrieval hook. That
sentence is only true once the hook is installed, so the hook goes first and its
outcome picks the wording: hook installed means Claude Code gets the shim
wording, hook skipped means every host gets the search-first wording, which is
true unconditionally. Writing the shim wording without the hook would tell the
model to stop searching in exchange for an injection that never arrives, which
is worse than doing nothing.

Every step is wrapped so that a failure becomes that step's line and the run
continues. A rules file you cannot write must never cost you the MCP
registration, and neither may cost you the doctor verdict that says which of
them landed. `setup` also runs on a locked encrypted store, which is the normal
case on a second machine, and lets `doctor` report the lock.

The individual verbs still exist and still work on their own:
`init`, `install-mcp`, `install-hooks`, `install-rules`, `doctor`.

## Which tool gets what

| Tool | MCP config | Rule block | Retrieval hook |
| --- | --- | --- | --- |
| Claude Code | printed command, not a written file | `~/.claude/CLAUDE.md` | yes, `~/.claude/settings.json` |
| Codex CLI | `~/.codex/config.toml` | `~/.codex/AGENTS.md` | no, see below |
| Gemini CLI | `~/.gemini/settings.json` | `~/.gemini/GEMINI.md` | no, see below |
| Grok CLI | `~/.grok/config.toml` | `~/.grok/AGENTS.md` | no, see below |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` \* | `~/.codeium/windsurf/memories/global_rules.md` \* | no, see below |
| Cursor | `~/.cursor/mcp.json` \* | none written, see below | no, see below |
| Claude Desktop | `claude_desktop_config.json` \* | none written, see below | no, see below |

\* **Vendor-documented, unverified on disk.** Windsurf, Cursor and Claude
Desktop are not installed on any machine we have checked, so we have never seen
these paths exist. If one of them ignores the store after `setup` says
`installed`, that is the first thing to suspect: check the app's own settings
for where it really keeps rules, and re-run `fimemory install-rules --file <path>`.
Every other row in the table has been seen on disk.

- **Claude Code** is the one host `install-mcp` does not write. The Claude Code
  CLI owns the schema of `~/.claude.json`, so we print
  `claude mcp add fimemory -s user -- ...` instead. Its rule block and its hook
  are written for you.
- **Cursor**: we write no Cursor rules file. Where Cursor keeps user-level
  rules, and whether it loads `~/.cursor/rules`, is **unverified**. Cursor is
  not installed on any machine we have checked and no Cursor documentation is on
  this disk. An earlier version of this page stated those limits as fact; they
  had never been read from a source, which is the same mistake as the
  `~/.grok/GROK.md` one below, so they are gone. Third-party evidence points
  the other way: Grok's own `12-project-rules.md` lists `~/.cursor/rules/` as
  a rules directory it scans. If you know the file Cursor reads,
  `install-rules --file <path>` writes the same block there.
- **Claude Desktop**: we write no Claude Desktop rules file. Whether it has an
  on-disk rules file at all is **unverified**. It is not installed on any machine we
  have checked. Its MCP config is written.
- **Gemini CLI** lets you rename its context file with `contextFileName` in
  `~/.gemini/settings