memany

A stdio MCP server that gives any coding agent a memory that survives the session, the tool and the machine.

Published as @any-ai/memany.

Two kinds of memory, each of which can apply to one repository or to all of them:

| kind | who can read it | typical content | | --- | --- | --- | | personal | only you, ever. Not teammates, not org admins | your habits, your shell, your opinions, half-formed ideas | | shared | everyone in your org | build commands, architecture decisions, conventions, traps |

Personal memories live in physically separate storage on the server (a distinct Postgres schema with no join path to organizations), so a bug in a team query cannot return them. A personal memory can be promoted to shared. Nothing can go the other way.

Works with Claude Code, Codex, Cursor, Gemini CLI, and anything else that speaks stdio MCP.

Step 1, required: install the server

Node 22 or newer.

npm install -g @any-ai/memany

That puts memany and memany-auth on your PATH. To run it from a clone instead:

git clone <this repo> && cd any
npm install
npm --prefix packages/memany run build
npm install -g ./packages/memany

Then sign in once. This stores a token in the macOS keychain, or in a 0600 file elsewhere, and records the service url:

memany-auth login
memany-auth whoami

After that no config file needs to hold a secret.

Claude Code

claude mcp add memany -s user -- memany

-s user makes it available in every project. Use -s project to commit it to the repo instead. Check it with claude mcp list.

Codex

Add this to ~/.codex/config.toml, or to .codex/config.toml for one project:

[mcp_servers.memany]
command = "memany"
args = []

Or from the CLI:

codex mcp add memany -- memany

Check it with codex mcp list, or type /mcp in the Codex TUI.

Any other stdio client

Cursor reads ~/.cursor/mcp.json (or .cursor/mcp.json per project). Gemini CLI reads the mcpServers object in its settings.json. Both take the same block:

{
  "mcpServers": {
    "memany": {
      "command": "memany",
      "args": []
    }
  }
}

If you would rather not sign in, pass credentials by environment instead. This works in every client above, but it puts a token in a config file:

{
  "mcpServers": {
    "memany": {
      "command": "memany",
      "args": [],
      "env": {
        "ANY_API_URL": "https://memory.example.com",
        "ANY_API_TOKEN": "any_..."
      }
    }
  }
}

Step 2, required: tell your agent to use it

Installing the server is not enough. An MCP server can advertise itself through the protocol's instructions field, and we measured that this is not sufficient: Codex ignored it entirely. What does work is an explicit instruction in the agent's own instructions file.

Paste the block below into whichever file your agent already reads:

| agent | for every project | for one project | | --- | --- | --- | | Claude Code | ~/.claude/CLAUDE.md | ./CLAUDE.md or ./.claude/CLAUDE.md | | Codex | ~/.codex/AGENTS.md | ./AGENTS.md | | Gemini CLI | ~/.gemini/GEMINI.md | ./GEMINI.md | | Cursor | a rule file under ~/.cursor/rules/ | a rule file under .cursor/rules/ |

Codex reads every AGENTS.md from the project root down to your working directory, so a nested one works too.

## Memory

You have a persistent memory through the `memany` MCP server. It outlives this session.

- At the start of a session, call `session_context` once. Do it before you read files, plan, or
  answer. It is cheap and it is capped.
- Call `recall` before you assume how this project is built, tested, deployed or reviewed, and
  before you ask me something a previous session may already have been told.
- Call `remember` the moment I state something durable: a preference, a convention, a gotcha, a
  decision, a command that works. Do not wait to be asked. One fact per call, one sentence.
- Choose `kind` by asking who the fact is true for. `personal` when it is true of me and not of the
  code: my habits, my machine, my opinions, anything I said with "I" or "my". `shared` when a
  colleague hitting the same wall would need it. When unsure, use `personal`; it can be promoted
  later, and a shared memory can never be made private again.
- Only call `promote` when I ask you to share something with the team.
- Do not store secrets, tokens, or anything that is stale next week.

Trim it if you like, but keep the first three bullets. They are the difference between the tools being used and being ignored.

The tools

| tool | what it does | | --- | --- | | remember | Store one fact. Takes note, kind (personal or shared), and an optional project. | | recall | Read everything that applies here, in four labelled groups. Optional query to search. | | session_context | A short, budgeted memory block for the top of a session. Cheaper than recall. | | promote | Move one of your personal memories into shared team memory. One way, author preserved. | | forget | Delete a memory by the id recall printed. |

recall returns the four groups clearly labelled, so the model can tell private from team:

Your personal memory, applies everywhere (only you can see this):
- I want plain language with no emoji in every reply (2026-08-07, id=46b35e45-...)

Your personal memory for github.com/acme/widgets (only you can see this):
- I debug widgets with console.log and delete them before committing (2026-08-07, id=e8b3be0c-...)

Shared team memory, applies everywhere:
- The team reviews every PR within one working day (Alice Author, 2026-08-07, id=57e5d5ed-...)

Shared team memory for github.com/acme/widgets:
- Widgets deploys from the release branch only (Alice Author, 2026-08-07, id=f5e915e8-...)

Which project a memory belongs to

The project argument on remember is optional and you rarely need it:

• omitted: the repository you are in right now, detected from git remote get-url origin
• "everywhere": no repository, so the fact follows you into every repo
• "acme/widgets" or a full git remote url: that specific repository

Remote urls are normalised, so [email protected]:Acme/Widgets.git, https://github.com/acme/widgets and acme/widgets are all the same project.

Configuration

Everything comes from the environment or from ~/.any. Nothing is read from a config file the agent controls.

| variable | meaning | | --- | --- | | ANY_API_URL | Memory service base url. Falls back to the url saved by memany-auth login. | | ANY_API_TOKEN | Bearer token. Falls back to the keychain, then a 0600 credentials file. | | ANY_STATE_DIR | Where credentials live. Default ~/.any. | | ANY_REPO_REMOTE | Override repository detection instead of shelling out to git. | | ANY_SESSION_CONTEXT_BUDGET | Character budget for session_context. Clamped to 200..20000. |

Credentials resolve in this order: environment, then ~/.any/credentials.json, then the macOS keychain (any-cli / api-token), then the legacy api-url and api-token files.

The server never writes memories to disk. With no service configured, every tool fails with a clear message rather than quietly saving somewhere only you can see. Losing the connection should look like a failure, not like success.

stderr stays completely silent on the happy path, because several TUI clients treat any child output as protocol corruption. Errors come back as MCP tool errors instead.

Talking to the API directly

GET /v1/memories always returns an object with items, next_cursor and text. items is always present, and is [] when there is nothing to show, so you never have to test for a missing key:

{ "items": [], "next_cursor": null, "text": "No shared memories yet.", "authors": [] }

Those three keys are the stable contract. Further keys may be added, like authors above, so read the ones you need rather than asserting on the whole object.

Any non-2xx response is a FastAPI error body instead, with a single detail key and no items:

{ "detail": "invalid or missing api token" }

So check the status code before reading items. GET /v1/memories/context is a different shape on purpose: { items, text, used_chars, budget, truncated }, where budget must be between 200 and 20000.

Account commands

memany-auth login                 # sign in through the service and store a token
memany-auth whoami                # who the stored token belongs to
memany-auth invite [email protected]   # add a teammate, --role member|admin
memany-auth members               # everyone in your org
memany-auth logout                # forget the token

License

MIT