How to Give Claude Code Memory on VPS

Wetin 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: one append-only log of wetin happen, and one short summary of where you stop. Local Python summarizer wey dey run for the machine wey you dey work on dey produce both files, so the memory itself no dey use any API tokens.

The gap wey e dey fill small but e dey happen every time. You close session for your VPS on Tuesday. On Wednesday, Claude Code no know anything about Tuesday. You go explain the project again by hand, or you allow the model read half of the repository again make e understand wetin dey happen. Both options dey use tokens, and the second one dey use plenty of them.

Recall version 0.4.0 na the current version as of July 2026, and MIT na the license wey cover the project. E na plugin. 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.

What hooks dem write, and when

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

• SessionStart dey fire when startup, resume, or clear happen. E dey show context.md so the session go open with your summary for view.
• 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/

You suppose see history.md with content inside. You fit no see context.md at all, and na the default behaviour, no be fault. auto_save_context na off unless you set am, so e go write the summary 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 wey come with am:

{
  "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 live. Keep am inside the project.
• capture_history dey turn the history.md log on or off.
• auto_save_context dey accept off or on_end, and e default to off.
• summary_sentences na how many sentences go remain inside 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 write enter disk.
• include_git dey add the current diff and recent commits to the summary.
• max_input_chars dey limit how much of history.md summarizer go read for one pass.

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

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

To pause capture for some time without touching 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 much token?

E depend on wetin the alternative be. Loading summary when session start no cost plenty. But wetin e dey replace fit cost plenty, because model wey no remember your project go rediscover am 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 na normal figures for mid-size project, no be measurement for your own project. Recall summary dey load with about 1,200 tokens. 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 model rediscover the project by reading files, e go dey between the two, near 30,000 tokens, and this number go grow as repository dey grow. The CLAUDE.md row dey there to show scale: e cheaper because e short and static, and e tell model your standing rules instead of wetin happen last night.

Measure your own numbers. One token na roughly four characters of English prose, and for code e fit be small pass that. If you also dey send the summary to local model for the same VPS, check the context window wey e dey enter before you trust the resume, because Ollama dey truncate long prompts for small default context length instead of telling you say e drop the ending.

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

Inside session, /context dey show wetin dey loaded inside context window now, while /cost dey report the session totals. Start one session from cold, then start the next one with summary already in place, and compare dem. For complete picture of where session tokens really dey go, how Claude Code dey spend tokens get the breakdown.

One thing dey qualify this claim. Summary dey load whenever session start, so summary wey you never use na small extra cost, no be saving. Keep summary_sentences near the default unless your sessions dey run long. Quieter session dey help for the other side, because agent wey you direct toward the smallest change wey work 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 dem no dey write anything

No .recall/ directory after one full session. The hooks no run. Type /recall:show to confirm say the plugin load, then run python3 -V. The hook command first try python3 and second try python, so any box wey no get both no go write anything, and e no go show error.

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 and allow the SessionEnd hook to handle am.

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

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

The summary no plenty after long session. max_input_chars limit the 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 after that, then check ls -la .recall/ again to confirm say fresh history.md don appear.

Wey Recall dey stop

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

The summarizer na extractive. TextRank dey pick sentences wey already dey inside history.md, so e no dey judge whether decision correct. Wrong turn 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, and nothing stop you from editing am.

No search dey inside. You get one current summary and one growing log for each project, but no queryable memory across projects. If question na wetin you decide about database three weeks ago, you dey grep history.md. E no carry anything sideways too: two sessions wey open on the same VPS at once no fit see each other's logs. So when one need know wetin the other dey do, sessions fit pass text between themselves directly while dem dey run.

E no help inside one session. Context window wey fill up for the middle of session na different problem with different fixes, and managing the context window inside one session na companion piece to this guide.

By design, system dey treat the summary as untrusted input. context.md dey injected inside fenced block with label, and Claude go ask before e rely on am. This design dey necessary because committed .recall/ directory na place where anybody wey get commit access fit write text wey your agent go read. How often the agent go stop to ask about wetin e read depend on the permission mode wey the session start with, and auto mode go become the Claude Code default on 14 August 2026. 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 dey target common patterns like API keys, tokens, PEM blocks and .env assignments. Read .recall/ before you commit am.

The version number dey honest about the maturity level. For 0.4.0 in July 2026, config keys and file layout fit still change between releases, so read changelog before you upgrade setup wey you depend on.

FAQ

.recall/context.md dey send my code or transcripts go 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 dey work when machine offline. The trade-off be say summary na extractive: e dey select sentences from your log instead of writing new ones.

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

auto_save_context default na off, so the summary go regenerate only when you run /recall:save. Set "auto_save_context": "on_end" for recall.config.json make e rewrite am when each session end. If history.md miss too, e mean say the hooks no dey run at all: confirm say plugin load with /recall:show, then confirm say python3 -V dey 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 stop. These na typical figures. 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 deliberately: the standing rules and build commands. context.md dey generate from wetin actually happen for last session, so e hold the migration wey stop halfway and wey you no go think to write down. Keep both.

One VPS fit hold memory for several projects?

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