# Memory (/docs/rlx/memory)

A fresh Claude Code session knows nothing about you or your repo. It greps
around, asks what you already told the last session, and repeats the mistake
you corrected yesterday. rlx fixes that at the start of every session:
each one begins with what you asked it to remember and the project's
conventions, and can ask a symbol index where code lives instead of grepping
for it.

There is nothing to run once it is set up. Claude Code's hooks hand the context
over as each session starts. Memory is also the one part of rlx you can
use on its own: no fleet, no tmux, no fleet UI.

## Set it up [#set-it-up]

If you ran the one-line installer, or the [Quickstart](/docs/rlx/quickstart),
memory is already on. For memory alone you need
[uv](https://docs.astral.sh/uv/) and Claude Code:

```sh
UV_PYTHON_DOWNLOADS=automatic uv tool install --python 3.13 aisquare-cli
cd path/to/your/repo
rlx init --local --agent claude-code
```

`init` registers the repo as a project and installs rlx's hooks into
Claude Code. The [Claude Code plugin](/docs/rlx/install#or-as-a-claude-code-plugin)
gives you the same hooks without installing rlx first.

## Tell it what to remember [#tell-it-what-to-remember]

```sh
rlx remember --user "prefer pytest over unittest"         # every project
rlx remember "releases are cut from a tag, never from main" # this project
rlx context add "run make check before pushing" --project  # the same, long form
```

Memory has two pools:

* **user**, with `--user`: follows you into every project. Your preferences,
  your style, the tools you reach for.
* **project**, the default: belongs to the repo you are in. Its conventions,
  its gotchas, how it is built and released.

`remember` is shorthand for `context add`, and both take `--tag` (repeat it for
several tags). Git worktrees resolve to their main repository, so every branch
you have checked out side by side shares one project pool.

When you add a project (`rlx project onboard`, `init`, Welcome or `+` in
`rlx`), rlx seeds its pool with one fact per marker it finds at the root,
such as `pyproject.toml`, `package.json` or a `Makefile`. A second run adds
nothing; `rlx project onboard --refresh` reads the markers again and adds
only what is new.

## See and change what is in scope [#see-and-change-what-is-in-scope]

```sh
rlx context list              # your user pool plus this project's
rlx context search pytest     # full-text search, in any script
rlx context show a3f2         # one entry; ids work by any unique prefix
rlx context edit a3f2         # opens it in $EDITOR
rlx context remove a3f2       # forget it
rlx context promote a3f2      # move a project entry to your user pool
rlx context preview           # the entries a new session would be handed
```

`context preview` shows the entries in scope. A session's start hook also
leaves out any a loaded `CLAUDE.md` already holds, and on a team adds the
board's block, so a session can receive a little less, or more, than the
preview. `rlx inject` prints the block by hand, and `rlx why`
explains the last `rlx inject`: what it printed and why. It does not see
what a hook handed a session, so on a machine that only uses the hooks it says
nothing has been injected yet.
`rlx context export out.md` and `rlx context import notes.md` move
memory between machines as Markdown (or JSON with `--format json`).

## What a new session receives [#what-a-new-session-receives]

Each session starts with your context entries in scope: the user pool plus the
active project's. A preference that a `CLAUDE.md` Claude Code already loads
holds is left out, so the agent does not read it twice.

A session on a team (a fleet agent, or one launched into a role) also gets the
board and its protocol. A solo session gets neither, and carries almost
nothing from rlx beyond your entries.

## Prompt history [#prompt-history]

In a project you added, rlx records each prompt you type, and
`rlx log` shows the project's history. In any other folder no prompt is
kept; only the session's token counts reach
[Usage & stats](/docs/rlx/usage-and-stats).

```sh
rlx log                                # this project's recent prompts
rlx config set capture.enabled false   # record no prompt anywhere
```

With `capture.enabled = false`, nothing is stored and `rlx log` stays
empty. Teammate updates still arrive. A config file that cannot be read
records no prompt either.

## Find code: the symbol index [#find-code-the-symbol-index]

Each project has a symbol index: where a name is defined, who uses it, and
what already looks like it. Ask it before you grep, and before you write a
helper that may already exist:

```sh
rlx code find spawn                 # where a name is defined
rlx code refs nudge_manager         # every use: calls, attribute reads, annotations
rlx code similar parse_duration     # like-named definitions, before you write one
rlx code index --status             # what the index holds, and whether it is behind
```

The index is built in the background when a project is added and refreshed at
each session start, reading only the files that changed. It indexes the
project's root checkout, so a coder in a fleet worktree asks the same index,
and it lives in `~/.aisquare/projects/<id>/code/`, apart from your memory:
deleting it loses nothing. Nothing leaves the machine.

Python needs nothing extra. TypeScript and JavaScript need the `code` extra
(see [Install](/docs/rlx/install#optional-extras)). It reads
git's file list, less binaries, files over `code.max_file_kb` (1024) and a
built-in ignore list (`node_modules`, virtualenvs, build output, worktrees)
that `code.ignore` extends:

```sh
rlx config set code.ignore '**/fixtures/**,docs/generated/**'
```

Over MCP, `rlx serve` offers the same as one tool, `code_lookup`, once
the project has an index. See [Remote agents](/docs/rlx/remote-agents).

## Next [#next]

<Cards>
  <Card title="Quickstart" href="/docs/rlx/quickstart" description="Add a manager and coders that start from this memory." />

  <Card title="Reference" href="/docs/rlx/reference" description="Every command, setting, path and hook." />
</Cards>
