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 .md files** 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.

• push replaces the server snapshot entirely (latest snapshot only, no history).

• pull is 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 --path directory (push/index), writes to --path directory (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 .md files 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/

-

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

• **.md files 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 login or npx atxp@latest agent register first.

• **--path is required** — there is no auto-detection of workspace location.

• Local search requires @zvec/zvec — install with npm install @zvec/zvec before 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.