ATXP Memory — Agent Memory Management
Manage your agent's .md memory files: back up and restore to/from ATXP cloud servers, and search your local memories using zvec vector similarity search.
Capabilities
| Capability | Description |
|---|---|
| Cloud Backup | Push/pull .md files to ATXP servers for disaster recovery |
| Local Search | Index .md files into a local zvec vector database, then search by natural language query |
| Status | View cloud backup info and local index statistics |
Security Model
- Only
.mdfiles are collected and transmitted (push/pull). No credentials, JSON configs, binaries, or other file types are ever sent. - Files are sent to ATXP servers over HTTPS, associated with the authenticated agent's identity.
pushreplaces the server snapshot entirely (latest snapshot only, no history).pullis non-destructive — it writes server files to the local directory but does not delete local files absent from the server.- Local search index is stored in a
.atxp-memory-index/subdirectory inside--path. It never leaves the local machine. - index and search do not require authentication or network access.
- Filesystem access: reads from
--pathdirectory (push/index), writes to--pathdirectory (pull) and--path/.atxp-memory-index/(index). No other directories are touched. - No modification of OpenClaw config or auth files.
When to Use
| Situation | Command |
|---|---|
| After meaningful changes to SOUL.md, MEMORY.md, or at end of session | push |
| Bootstrapping a fresh workspace or recovering from environment loss | pull |
| After updating memory files and before starting a task that requires recall | index |
| Looking for relevant context in past memories | search |
| Verify backup exists before risky operations | status |
Commands Reference
| Command | Description |
|---|---|
npx atxp@latest memory push --path <dir> | Recursively collect all *.md files from <dir> and upload to server |
npx atxp@latest memory pull --path <dir> | Download backup from server and write files to <dir> |
npx atxp@latest memory index --path <dir> | Chunk .md files by heading and build a local zvec search index |
npx atxp@latest memory search <query> --path <dir> | Search indexed memories by similarity |
npx atxp@latest memory status [--path <dir>] | Show cloud backup info and/or local index stats |
Options
| Option | Required | Description |
|---|---|---|
--path <dir> | Yes (push/pull/index/search) | Directory to operate on |
--topk <n> | No (search only) | Number of results to return (default: 10) |
How Local Search Works
-
Indexing (
memory index):- Scans all
.mdfiles recursively from--path - Splits each file into chunks at heading boundaries (h1/h2/h3)
- Converts each chunk into a 256-dimensional feature vector using locality-sensitive hashing (unigrams + bigrams)
- Stores vectors and metadata in a local zvec database (HNSW index) at
<path>/.atxp-memory-index/
- Scans all
-
Searching (
memory search):- Converts the query text into the same vector representation
- Performs approximate nearest neighbor search via zvec's HNSW index
- Returns the top-k most similar chunks with file paths, headings, line numbers, and similarity scores
The search is purely local — no network requests, no API keys, no cost. Re-index after modifying memory files.
Path Conventions
Typical OpenClaw workspace paths:
~/.openclaw/workspace-<id>/
~/.openclaw/workspace-<id>/SOUL.md
~/.openclaw/workspace-<id>/MEMORY.md
~/.openclaw/workspace-<id>/memory/
~/.openclaw/workspace-<id>/AGENTS.md
~/.openclaw/workspace-<id>/USER.md
Backward Compatibility
The backup command is still accepted as an alias for memory:
npx atxp@latest backup push --path <dir> # works, same as memory push
npx atxp@latest backup pull --path <dir> # works, same as memory pull
npx atxp@latest backup status # works, same as memory status
Limitations
.mdfiles only — all other file types are ignored during push/index and not present in pull.- Latest snapshot only — each push overwrites the previous backup. There is no version history.
- Requires ATXP auth for cloud operations — run
npx atxp@latest loginornpx atxp@latest agent registerfirst. --pathis required — there is no auto-detection of workspace location.- Local search requires @zvec/zvec — install with
npm install @zvec/zvecbefore using index/search. - Feature-hash embeddings — local search uses statistical text hashing, not neural embeddings. It works well for keyword and phrase matching but is not a full semantic search. For best results, use specific terms from your memory files.