atxp-memory_skill

Overview

This skill manages an agent's Markdown memory files with cloud backup, restore, and fast local vector search. It provides commands to push and pull .md snapshots to ATXP cloud, build a local zvec index, and run similarity searches over memory chunks. The tool enforces .md-only handling and keeps the search index strictly local for privacy.

How this skill works

The skill collects only .md files from the specified path for cloud operations and transmits them over HTTPS to a single server snapshot (push replaces the snapshot; pull writes files non-destructively). Locally, it chunks Markdown by headings, converts chunks into 256-dimensional feature hashes, and stores them in a zvec HNSW index at <path>/.atxp-memory-index/. Search converts queries to the same hashes and returns the top-k most similar chunks with file paths, headings, line numbers, and scores.

When to use it

• Push after important edits to SOUL.md, MEMORY.md, or session changes to ensure a cloud snapshot exists.
• Pull when bootstrapping a fresh workspace or recovering from data loss.
• Index before tasks that require recall so local search returns up-to-date context.
• Search when you need relevant past context or examples from your agent memories.
• Check status before risky operations to verify a backup exists.

Best practices

• Require --path explicitly to avoid accidental workspace selection; always confirm the path you supply.
• Run index after any .md edits so search results reflect the latest content.
• Use descriptive headings in Markdown so chunking produces meaningful, searchable fragments.
• Install @zvec/zvec locally to enable index/search functionality (index/search do not use the network).
• Keep sensitive non-Markdown data outside the memory path—only .md files are transmitted or indexed.

Example use cases

• Create a cloud snapshot before deploying code or deleting a workspace: npx atxp@latest memory push --path <dir>.
• Recover a lost workspace by pulling the latest cloud snapshot: npx atxp@latest memory pull --path <dir>.
• Prepare for a long-running task by indexing memory files so the agent can quickly find prior decisions: npx atxp@latest memory index --path <dir>.
• Locate a past configuration or design note with a natural language query: npx atxp@latest memory search "database migration notes" --path <dir>.
• Verify backup state and local index stats with: npx atxp@latest memory status --path <dir>.