Agent memory management — cloud backup, restore, and local vector search of .md memory files

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 1. 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/ 2. 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: Backward Compatibility The backup command is still accepted as an alias for memory : 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.

atxp-memory