Memory for agents
that shows its work.

1 Install it.

$ uvx alice-memory install

Or, without uv:

$ pip install alice-memory && alice-memory install

The first command needs uv. The second needs Python 3.12 or later: with no uv, install points your hosts at the alice-memory program pip installed. Your notes go in ~/.alice; to keep them somewhere else, add --data-dir with an absolute path, or one that starts with ~/, the first time you install. The installer writes config for Claude Desktop, Claude Code, Cursor and OpenClaw, and adds a SessionStart hook for Claude Code and Cursor. Hermes, OpenCode and Codex are opt-in, and any --host replaces the default set: alice-memory install --host hermes writes Hermes only. To add Hermes to the four defaults, pass all five: --host claude-desktop --host claude-code --host cursor --host openclaw --host hermes. It serves three MCP tools over stdio against a single SQLite file in the directory you chose: remember, recall, continue. Capture, the context pack and the other tools are not in the default set. Set ALICE_MCP_FULL_TOOLS=1 in the same config to list them.

Using Codex? Codex is opt-in. This writes Codex only:

$ uvx alice-memory install --host codex

It adds the MCP entry to config.toml in Codex’s home (~/.codex, or CODEX_HOME when set) and a SessionStart hook to hooks.json there. Codex skips that hook until you trust it: open Codex, choose Review hooks at “Hooks need review” and trust alice-memory-session-start, or use /hooks. Check the entry with codex mcp get alice.

Alice is now also a Claude Code plugin:

$ claude plugin marketplace add samrusani/AliceMemory
$ claude plugin install alice-memory@alicememory

Or keep using alice-memory install. Pick one, not both.

The plugin keeps notes in ~/.alice. For another folder, add --config data_dir=/ABSOLUTE/PATH/TO/.alice to the install command. Already ran alice-memory install? Remove its Claude Code entries first: run claude mcp remove alice --scope user and delete the alice-memory-session-start hook from ~/.claude/settings.json. To update, run claude plugin update alice-memory@alicememory.

New in v0.19.0. Codex support, opt-in with --host codex. A Claude Code plugin. A session brief that cuts a long note at 1,500 characters instead of dropping it, stays under 9,500 characters and leaves out superseded facts. A --data-dir that is empty or relative now stops the server; v0.18.0 accepted a relative one and made a vault in whatever folder the host started in. The v0.19.0 release notes have the rest.

Upgrading from v0.18.0? With pip, run pip install -U alice-memory==0.19.0. With uv, run uvx alice-memory@0.19.0 --version once; it prints the version your hosts get. Then restart your hosts. Check every --data-dir in your host config: it must be an absolute path or start with ~/. A relative path, or the literal text ${HOME}/.alice, now stops the server. Your SQLite vault opens as it is; there is no schema change. Run alice-memory doctor: it now also lists a stored source that holds a key shaped like an AWS access key id. If it lists one, rotate that key. On Hermes, a re-run keeps comments in the alice block, or refuses and prints the block when it has a change to make. Scripts that read folder import receipts will see the file name in each withheld item. Coming from v0.17.0? Read the v0.18.0 release notes too.

2 Or wire it by hand.

Prefer to edit the config yourself? These snippets still run the MCP server directly.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "alice": {
      "type": "local",
      "command": ["uvx", "alice-memory", "mcp", "--data-dir", "/ABSOLUTE/PATH/TO/.alice"]
    }
  }
}

{
  "mcpServers": {
    "alice": {
      "command": "uvx",
      "args": ["alice-memory", "mcp", "--data-dir", "/ABSOLUTE/PATH/TO/.alice"]
    }
  }
}

{
  "mcpServers": {
    "alice": {
      "command": "uvx",
      "args": ["alice-memory", "mcp", "--data-dir", "/ABSOLUTE/PATH/TO/.alice"]
    }
  }
}

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "uvx --from alice-memory alice-memory-session-start --data-dir /ABSOLUTE/PATH/TO/.alice"
          }
        ]
      }
    ]
  }
}

{
  "mcpServers": {
    "alice": {
      "command": "uvx",
      "args": ["alice-memory", "mcp", "--data-dir", "/ABSOLUTE/PATH/TO/.alice"]
    }
  }
}

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "command": "uvx --from alice-memory alice-memory-session-start --data-dir /ABSOLUTE/PATH/TO/.alice"
      }
    ]
  }
}

mcp_servers:
  alice:
    command: "uvx"
    args:
      - "alice-memory"
      - "mcp"
      - "--data-dir"
      - "~/.alice"
    env:
      ALICE_MEMORY_DATA_DIR: "~/.alice"

{
  "mcp": {
    "servers": {
      "alice": {
        "command": "uvx",
        "args": ["alice-memory", "mcp", "--data-dir", "~/.alice"]
      }
    }
  }
}

$ openclaw mcp add alice \
    --command uvx \
    --arg alice-memory --arg mcp \
    --arg --data-dir --arg ~/.alice

$ openclaw mcp probe
- alice: 3 tools

[mcp_servers.alice]
command = "uvx"
args = ["alice-memory", "mcp", "--data-dir", "/ABSOLUTE/PATH/TO/.alice"]

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "uvx --from alice-memory alice-memory-session-start --data-dir /ABSOLUTE/PATH/TO/.alice --format markdown",
            "timeout": 120,
            "additionalContextLimit": 0
          }
        ]
      }
    ]
  }
}

3 See it work.

$ uvx alice-memory demo --vault ~/Notes

It imports a Markdown folder and prints the one passage a new session will quote back.

Already have notes? alice-memory import-markdown --from ~/Notes or alice-memory import-chatgpt --from conversations.json. A line that holds a credential is stored as withheld, and the rest is imported. The receipt says where each withheld item was: the file and line for a notes folder, the conversation for ChatGPT. The check is a pattern check: it misses some formats and refuses some harmless notes.

4 Then talk to your agent.

That is the whole setup. On Codex, the brief starts once you trust the hook. Configure an embeddings endpoint if you want vector search; without one, retrieval runs on full-text alone.