How to Give Claude Code Memory on VPS

Wetín Recall dey do for Claude Code memory

Recall na Claude Code plugin wey dey give each project memory across sessions. E dey write two markdown files inside .recall/ folder for your project: append-only log of wetin happen, and short summary of where you stop. Local Python summarizer wey dey run for the machine wey you dey work on produce both files, so the memory itself no dey use any API tokens.

The gap wey e dey fill small but e dey happen steady. You close session for your VPS on Tuesday. On Wednesday, fresh session no dey load Tuesday conversation automatically, even though Claude Code built-in auto memory fit keep notes across sessions. If those notes no cover where you stop, you go explain the project again by hand, or allow the model read half the repository again to figure am out. Both options dey cost tokens, but the second one dey cost plenty.

Recall version 0.4.0, wey dem release on 18 July 2026, still be the latest release as of October 2026, and the project get MIT license. Na plugin e be. Nothing inside am dey make network call.

Wetin you need for the VPS

Recall capture hooks na Python scripts wey dey come with the plugin. E no get any third-party dependency, so the only real requirement na interpreter.

python3 -V

Ubuntu 24.04 answer Python 3.12.3. Recall support Python 3.9 and newer versions. Some minimal container images no get interpreter at all, and shell go answer python3: command not found. Install one before you continue.

sudo apt update && sudo apt install -y python3

NumPy na optional accelerator for one step of the summarizer. You no need am.

python3 -c "import numpy"

ModuleNotFoundError: No module named 'numpy' na acceptable answer for here. The summarizer get pure-Python path, and the project test suite dey check say both paths select the same sentences.

Session memory matter more for server than laptop, because server work dey come as short visits wey spread across days. If you already get Claude Code wey dey run inside tmux for VPS, Recall na the part wey carry yesterday session enter today own.

Install Recall from the plugin marketplace

Na two commands you go type inside one Claude Code session:

/plugin marketplace add raiyanyahya/recall
/plugin install recall@recall

The second command dey read plugin@marketplace. Both names na recall for here. E fit look like copy-paste mistake, but e no be mistake.

Check the installation by running one of the plugin own commands:

/recall:show

/recall:show dey print the current summary. For brand-new project, nothing dey to print yet. So wetin you really dey check na whether the command dey exist at all. If Claude Code no recognise /recall:show, the plugin no load, and no hook go run.

If you wan run am from one checkout, clone the repository and validate am first:

git clone https://github.com/raiyanyahya/recall ~/recall
cd ~/recall && claude plugin validate .

claude plugin validate . dey read the manifest for .claude-plugin/ and report whether the plugin structure correct. Then start Claude Code from your project directory with claude --plugin-dir ~/recall.

Wetin the hooks dey write, and when

Recall dey register three Claude Code hooks. Each one dey run a Python script from the plugin directory.

• SessionStart dey fire for startup, resume, and clear. E dey show context.md so the session go open with your summary visible.
• Stop dey fire every time Claude finish one response. E dey append that turn to the log.
• SessionEnd dey fire when the session close, and e fit regenerate the summary.

Two files dey come out from this, both inside .recall/.

• history.md na the append-only record: prompts, responses, files wey dem touch, and commands wey dem run.
• context.md na the generated digest: the goal, summary, next steps, files wey dem touch, commands wey dem run, and git context.

After one real session, check the directory.

ls -la .recall/

When capture dey enabled, no pause marker dey present, and transcript dey available, you suppose see history.md with content inside. You fit no see context.md at all, and that one na the default behaviour, no be fault. auto_save_context na off unless you set am, so the summary go write only when you request am:

/recall:save

That command dey run the local summarizer over history.md and rewrite context.md. The algorithm na TF-IDF (term frequency, inverse document frequency) scoring wey dey feed TextRank sentence ranking. E deterministic and extractive, meaning say e dey select sentences wey already dey inside your log. No model dey run, so the step free and e dey work when the machine offline.

Configure Recall for one project

Configuration dey inside one recall.config.json file for the project root. Na these defaults the software ship with:

{
  "output_dir": ".recall",
  "capture_history": true,
  "summary_sentences": 8,
  "redact": true,
  "include_git": true,
  "max_input_chars": 200000
}

• output_dir set where the two files dey. Keep am inside the project.
• capture_history dey turn the history.md log on or off.
• auto_save_context accept off or on_end, and e dey default to off.
• summary_sentences na how many sentences go remain for context.md. If you increase am, summary go longer and load for session start go slightly bigger.
• redact dey remove common secret patterns before anything enter disk.
• include_git dey add current diff statistics and recent commits to the summary.
• max_input_chars dey limit how much history.md the summarizer go read for one pass.

For project wey dey run for VPS, automatic saving na the useful change, because session for server often dey end when terminal disconnect rather than when you decide to stop.

{
  "auto_save_context": "on_end",
  "summary_sentences": 12
}

To pause capture for some time without changing config, create the pause marker. Delete am to start capture again.

touch .recall/.capture-paused

Do this before session wey you go handle production credentials, because redaction na filter and e no be guarantee. Na the same reason make you keep secrets away from AI agents generally: secret wey safe na the one wey agent never see.

Recall dey save how many tokens?

E depend on wetin the alternative be. Loading summary when session start cheap. The thing wey e replace fit cost plenty, because model wey no remember your project go discover am again by reading files.

[
  {
    "label": "Recall context.md",
    "char_count": "4,800",
    "est_tokens": "1,200"
  },
  {
    "label": "Hand-written CLAUDE.md",
    "char_count": "3,200",
    "est_tokens": "800"
  },
  {
    "label": "Re-reading the repo",
    "char_count": "120,000",
    "est_tokens": "30,000"
  },
  {
    "label": "Full transcript replay",
    "char_count": "340,000",
    "est_tokens": "85,000"
  }
]

These figures na typical ones for mid-size project, no be measurement of your own project. Recall summary dey load with about 1,200 tokens, and this match the project's published claim of one to two thousand tokens for resume. Replaying full previous transcript go load the whole conversation again, around 85,000 tokens. If you make the model discover the project again by reading files, the cost dey between the two, near 30,000 tokens, and this number dey grow as repository grow. The CLAUDE.md row dey there to show scale: e cheaper because e short and static, and e tell the model your standing rules instead of wetin happen last night.

Measure your own numbers. One token na roughly four characters of English prose, and slightly less for code. If you also dey give the summary to local model for the same VPS, check the context window wey e dey enter before you trust the resume, because Ollama default context length dey depend on available VRAM.

wc -c .recall/context.md .recall/history.md
echo $(( $(wc -c < .recall/context.md) / 4 ))

Inside session, /context dey show wetin don load into the context window now, while /cost dey report the session totals. Start one session without anything, start the next one with summary ready, then compare dem. For the full picture of where session tokens really dey go, how Claude Code dey spend tokens get the breakdown.

One caution dey keep this claim honest. Summary dey load every time session start, so summary wey you no ever use na small extra cost instead of saving. Keep summary_sentences near the default unless your sessions dey run long. Quieter session dey help for the other side too, because agent wey you push toward the smallest change wey works go leave shorter log for summarizer to rank.

Rebuild summary without session

If you clone the repository, summarizer get its own command line entry point. This one useful for VPS when session don die together with terminal and you still want the digest.

python3 ~/recall/scripts/make_context.py --help

The help output show the flags wey e accept: --cwd for project root, --transcript for specific transcript file, --quiet to stop output, and --harness to choose between claude and opencode. Point am to one project:

python3 ~/recall/scripts/make_context.py --cwd /srv/projects/api

E go read the session transcript and history.md, then write context.md inside the directory wey you pass. If you install am through marketplace, plugin dey inside directory wey Claude Code manage, and /recall:save na the supported way to do the same work.

Why nothing dey write

No .recall/ directory after full session. Check whether capture dey disabled, whether output directory dey configured for another place, or whether no transcript dey found before you conclude say hooks never run. Type /recall:show to confirm say plugin load, then run python3 -V. Hook command go try python3 first and python second, so any box wey no get both go fail with stderr and exit status 127. Claude Code go show non-blocking hook error notice wey carry the first line of stderr.

history.md dey grow but context.md no dey change. auto_save_context na off by default. Run /recall:save, or set the key to on_end make SessionEnd hook handle am.

The files dey appear under wrong project. Recall dey write relative to the directory wey Claude Code start from, so if you start session from your home directory, memory go enter there. Start from project root, and use ls -la .recall/ to find where the files really land.

Capture stop and nothing warn you. Check for pause marker with ls -a .recall/. Any .capture-paused file wey you create last week still dey do the work.

The summary short after long session. max_input_chars dey limit summarizer input to 200000 characters, so e go cut very long log. Rotate am.

mv .recall/history.md .recall/history-2026-07-30.md

Run one short session afterwards and check ls -la .recall/ again to confirm say fresh history.md don appear.

Where Recall dey stop

Recall na log plus summarizer, and e good make we clear wetin that one no cover.

The summarizer dey extract. TextRank dey pick sentences wey already dey inside history.md, so e no dey judge whether decision correct. Wrong direction wey dem record on Tuesday go read exactly like good decision on Wednesday. When matter serious, read context.md and correct am by hand. Na markdown file be that, and nothing stop you from editing am.

No search dey. You get one current summary and one growing log for each project, but no queryable memory across projects. If question be wetin you decide about database three weeks ago, you go grep history.md. E no provide live coordination: two sessions for the same project share the log file, but Recall no push new log entries enter the other session context. So when one session need know wetin the other dey do, sessions fit pass text directly between themselves while dem dey run.

E no help inside one session. When context window full during session, na different problem with different fixes, and managing the context window inside one session na the companion piece for this guide.

By design, the summary dey treated as untrusted input. context.md dey injected inside fenced block with label, and Claude dey ask before e rely on am. This design dey important because committed .recall/ directory na place where anybody with commit access fit write text wey your agent go read. How often the agent stop to ask about wetin e read depend on the permission mode wey session start with. With Claude Code v2.1.283 or later, auto mode don already become the built-in starting mode for interactive terminal and VS Code sessions on every plan and provider, so classifier rather than you dey review most actions; organizations with HIPAA configuration still start for Manual mode. Decide once whether .recall/ na personal or shared: add am to .gitignore for personal memory, or commit am and review am like any other contribution. If agent dey run unattended, running Claude Code safely on a VPS cover the wider boundary.

Redaction na best effort. E targets common patterns like API keys, tokens, PEM blocks and .env assignments. Read .recall/ before you commit am.

The version number dey show the maturity level honestly. For 0.4.0, wey still be the latest release for October 2026, config keys and file layout fit still change between releases, so read the changelog before you upgrade setup wey you depend on.

FAQ

Recall dey send my code or transcripts anywhere?

No. The capture hooks and summarizer na Python scripts wey dey run for your own machine. The plugin no hold any API key, and e no make any network call. Summarising dey use TF-IDF and TextRank instead of model, so the step cost nothing and e work when machine dey offline. The trade-off be say the summary na extractive: e select sentences from your log instead of writing new ones.

Why my .recall/context.md dey miss or old?

auto_save_context default to off, so the summary go regenerate only when you run /recall:save. Set "auto_save_context": "on_end" inside recall.config.json make e rewrite am whenever each session end. If history.md dey miss too, check capture_history, the .capture-paused marker, and whether session transcript dey available: running hooks skip writing history for those cases. Confirm say plugin load with /recall:show, then confirm say python3 -V answer for that box, because the hooks na Python scripts.

How much Recall dey save for each session?

Loading summary cost around 1,200 tokens, compared with typical 30,000 tokens for model wey need read your repository again to know where e dey. Those figures na typical ones. Measure your own with wc -c .recall/context.md and the /context command inside session. Compare cold start with one wey resume from summary.

I still need CLAUDE.md file?

Yes, and the two get different work. CLAUDE.md na wetin you write intentionally: the standing rules and build commands. context.md dey generate from wetin actually happen for last session, so e hold the half-finished migration wey you no go think to write down. Keep both.

One VPS fit hold memory for several projects?

Yes. Recall dey keep memory inside .recall/ for each project directory, so two projects for the same server go keep separate logs and separate summaries. Start Claude Code from project root every time, because the files follow the working directory, not the user account.