atxp-memory

SKILL.md

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.