OpenClaw Memory Reliability Pack v2

Start Here

This package is for people whose OpenClaw remembers too little, loses track of tasks, or gives different answers in fresh sessions than it gave earlier.

It adds a small reliability layer on top of OpenClaw. It does that by using a few plain Markdown files as the canonical source of truth:

• PROJECTS.md for project priorities, goals, status, and time allocation
• TASKS.md for open and closed tasks
• MEMORY.md for durable facts and explicit "remember this" requests
• a managed block in AGENTS.md that tells OpenClaw to update and read those files before answering

This package exists because many OpenClaw users run into the same three problems:

• important state given in conversation does not always get written durably
• fresh sessions can answer from stale fuzzy recall instead of current file state
• completed tasks can leak into "what's left" answers

This pack does not replace OpenClaw. It gives OpenClaw clearer files and stricter retrieval rules so memory and task handling become predictable.

If You Want Claude Or Codex To Do This For You

Paste this into your coding agent:

I have the OpenClaw Memory Reliability Pack in the current folder. Please install it safely into the real OpenClaw workspace, not a throwaway test profile unless I explicitly ask for one.

Do this exactly:
1. Open a shell in the folder that contains this README.
2. Run the installer in dry-run mode first.
3. Show me the workspace it detected and where that workspace came from.
4. If the workspace looks correct, run the real installer.
5. Run the verifier.
6. If verification fails, run the debug collector and summarize the failure.
7. Do not claim success unless the verifier passes.

What You Need First

• OpenClaw already installed on the target machine
• model access already working for the target OpenClaw instance
• shell access, either directly or through a coding agent

Helpful but optional:

• embeddings enabled for semantic memory support

Why OpenClaw Struggles To Remember

In practice, OpenClaw can struggle with memory and tasks for a few technical reasons:

• state given in normal conversation is not always turned into durable canonical files immediately
• fresh sessions can rely too heavily on fuzzy semantic recall instead of the newest current state
• task state can be ambiguous when there is no clear canonical split between open work and closed work
• recommendation answers can drift because the agent answers from recent conversation or embeddings instead of reading an authoritative workspace file first

That means a user can tell OpenClaw something important, get a correct answer once, and then get a weaker or inconsistent answer later.

What This Pack Does Technically

This pack fixes that by changing the storage and retrieval path, not by replacing OpenClaw.

Specifically, it introduces:

• PROJECTS.md as the canonical source for project priorities, focus, goals, status, and allocation
• TASKS.md as the canonical source for open and closed tasks
• MEMORY.md as the canonical source for durable facts and explicit remember-requests
• a managed block in AGENTS.md that tells OpenClaw to update those files before replying when new state is given
• retrieval rules that tell OpenClaw to read the correct canonical file before answering project, task, focus, or memory questions

In other words:

• current canonical file state wins over fuzzy recall
• open-task questions read open tasks only
• completed tasks stay in the closed section unless the user explicitly asks about completed work
• fresh-session answers are anchored to durable workspace state instead of chat history alone

The verifier then tests that behavior with real agent calls so you are not relying on the bot simply claiming it worked.

The Recommended Install Flow

This is the safest path:

1. Open a shell on the machine that runs OpenClaw.
2. Go into the unzipped package folder.
3. Run the installer in --dry-run mode first.
4. Confirm it found the real workspace.
5. Run the real install.
6. Run the verifier.
7. Only trust the install if verification passes.

This flow works well on headless Linux servers, including Railway deployments.

Headless Linux Tutorial

1. SSH into the server

Example:

ssh your-user@your-server

2. Go into the unzipped package folder

Example:

cd ~/openclaw-memory-reliability-pack-YYYYMMDD-HHMMSS

3. Run the dry-run first

If you know the profile:

bash install-openclaw-memory-reliability-pack.sh --profile YOUR_PROFILE --dry-run

If you want the installer to detect the active default workspace:

bash install-openclaw-memory-reliability-pack.sh --dry-run

Dry-run shows:

• which profile is being used
• which workspace was detected
• whether the workspace came from config, env vars, or fallback defaults
• which files would be created or patched
• warnings about existing files

4. Run the real install

bash install-openclaw-memory-reliability-pack.sh --profile YOUR_PROFILE

Or, if you want to target a workspace directly:

bash install-openclaw-memory-reliability-pack.sh --workspace /absolute/path/to/workspace

5. Run verification

bash verify-openclaw-memory-reliability-pack.sh --profile YOUR_PROFILE

The verifier does real openclaw agent --json checks, inspects the canonical files, tests fresh-session retrieval, and restores the original workspace files afterward so the test data does not stay behind.

6. If verification fails

Run:

bash collect-openclaw-memory-pack-debug.sh --profile YOUR_PROFILE

That writes a non-secret debug report inside:

.memory-reliability-pack-reports/

You can attach that report to a GitHub issue or send it to support.

Railway Tutorial

Typical Railway deployments use a workspace like:

/data/workspace

That is only an example. The installer does not assume that path blindly. It tries, in order:

1. --workspace
2. openclaw config get agents.defaults.workspace
3. OPENCLAW_WORKSPACE_DIR or CLAWDBOT_WORKSPACE_DIR
4. a documented fallback default

If you are running the release gate from your local machine with Railway CLI:

railway login --browserless

Then run the generic Railway gate helper from this repo:

bash railway-gate-openclaw-memory-reliability-pack.sh --project YOUR_PROJECT --service YOUR_SERVICE --environment YOUR_ENVIRONMENT

If you know the workspace path and want to force it:

bash railway-gate-openclaw-memory-reliability-pack.sh --project YOUR_PROJECT --service YOUR_SERVICE --workspace /data/workspace

What The Installer Changes

The installer is designed to be conservative:

• it patches only the managed block inside AGENTS.md
• it creates PROJECTS.md only if missing
• it creates TASKS.md only if missing
• it creates MEMORY.md only if missing
• it backs up existing files before changing anything
• it tries to enable session-memory
• it tries to run memory index --force

It does not overwrite existing PROJECTS.md, TASKS.md, or MEMORY.md.

What Success Looks Like

After install and verify:

• PROJECTS.md, TASKS.md, and MEMORY.md exist in the real workspace
• AGENTS.md contains the managed memory reliability block
• fresh-session retrieval answers from canonical files
• completed tasks do not leak into open-task answers
• seeded state is durably written to files
• rollback can restore the latest backup cleanly

Optional Smoke Test On A Separate Profile

If you want a throwaway local profile first:

bash smoke-test-openclaw-memory-reliability-pack.sh --profile mempack-smoke

Use this only if you intentionally want a test profile. The default recommendation is to install into the real active workspace after confirming the dry-run output.

Uninstall / Roll Back

If You Want Claude Or Codex To Remove It

Paste this:

Please remove the OpenClaw Memory Reliability Pack safely.

Do this exactly:
1. Detect the same workspace the installer used.
2. Run the uninstall script instead of editing files manually.
3. Restore the latest backup.
4. Show me which files were restored.
5. Tell me whether any pack-created files were left behind.

Manual uninstall

Run:

bash uninstall-openclaw-memory-reliability-pack.sh --profile YOUR_PROFILE

Or:

bash uninstall-openclaw-memory-reliability-pack.sh --workspace /absolute/path/to/workspace

If OpenClaw Fixes This Upstream Later

If OpenClaw eventually fixes these memory problems natively, you do not need to panic or rip this out immediately.

Recommended path:

1. Upgrade OpenClaw in a safe environment first.
2. Run this pack's verifier again.
3. Compare the new native behavior with the pack-assisted behavior.
4. If upstream behavior is now reliably correct for your workflow, uninstall the pack and rerun verification.
5. If upstream behavior is still inconsistent, keep the pack in place until native behavior is trustworthy.

In other words: treat this pack as a reliability layer you can keep until OpenClaw proves it no longer needs it.

Desktop / macOS Appendix

If you are on macOS instead of Linux:

1. Open Terminal
2. cd into the unzipped package folder
3. Run the same --dry-run, install, and verify commands shown above