ATXP Memory：AI代理记忆管理工具 - 云端备份与本地向量搜索

atxp-memory by atxp-dev/cli

72 周安装量

9 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/atxp-dev/cli --skill atxp-memory

AI/机器学习文件管理命令行工具

🇨🇳中文介绍

ATXP Memory — 代理记忆管理

管理代理的 .md 记忆文件：备份到 ATXP 云服务器及从服务器恢复，并使用 zvec 向量相似性搜索搜索本地记忆。

功能

功能	描述
云端备份	推送/拉取 `.md` 文件至 ATXP 服务器，用于灾难恢复
本地搜索	将 `.md` 文件索引到本地 zvec 向量数据库，然后通过自然语言查询进行搜索
状态查看	查看云端备份信息和本地索引统计信息

安全模型

仅收集和传输 .md 文件（推送/拉取）。绝不发送凭据、JSON 配置、二进制文件或其他文件类型。
文件通过发送到 ATXP 服务器，并与已认证代理的身份关联。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

896,800 周安装

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

120,000 周安装

AI Elements：基于shadcn/ui的AI原生应用组件库，快速构建对话界面

69,600 周安装

超能力技能使用指南：AI助手技能调用优先级与工作流程详解

52,100 周安装

场景	命令
对 SOUL.md、MEMORY.md 进行有意义更改后，或在会话结束时	`push`
引导全新工作区或从环境丢失中恢复时	`pull`
更新记忆文件后，在开始需要回忆的任务之前	`index`
在过去的记忆中寻找相关上下文时	`search`
在风险操作前验证备份是否存在时	`status`

命令	描述
`npx atxp@latest memory push --path <dir>`	从 `<dir>` 递归收集所有 `*.md` 文件并上传到服务器
`npx atxp@latest memory pull --path <dir>`	从服务器下载备份并将文件写入 `<dir>`
`npx atxp@latest memory index --path <dir>`	按标题对 `.md` 文件进行分块，并构建本地 zvec 搜索索引
`npx atxp@latest memory search <query> --path <dir>`	通过相似性搜索已索引的记忆
`npx atxp@latest memory status [--path <dir>]`	显示云端备份信息和/或本地索引统计信息

选项	必需	描述
`--path <dir>`	是（push/pull/index/search）	要操作的目录
`--topk <n>`	否（仅 search）	要返回的结果数量（默认：10）

索引 (memory index)：
- 从 --path 递归扫描所有 .md 文件
- 在标题边界（h1/h2/h3）处将每个文件分割成块
- 使用局部敏感哈希（unigrams + bigrams）将每个块转换为 256 维特征向量
- 将向量和元数据存储在 <path>/.atxp-memory-index/ 处的本地 zvec 数据库（HNSW 索引）中
搜索 (memory search)：
- 将查询文本转换为相同的向量表示
- 通过 zvec 的 HNSW 索引执行近似最近邻搜索
- 返回前 k 个最相似的块，包含文件路径、标题、行号和相似性分数

仅限 .md 文件——在推送/索引期间会忽略所有其他文件类型，拉取时也不会包含它们。
仅保留最新快照——每次推送都会覆盖之前的备份。没有版本历史记录。
云端操作需要 ATXP 认证——请先运行 npx atxp@latest login 或 npx atxp@latest agent register。
必须提供 --path——无法自动检测工作区位置。
本地搜索需要 @zvec/zvec——在使用索引/搜索功能前，请通过 npm install @zvec/zvec 安装。
特征哈希嵌入——本地搜索使用统计文本哈希，而非神经嵌入。它适用于关键词和短语匹配，但不是完整的语义搜索。为获得最佳效果，请使用记忆文件中的特定术语。

🇺🇸English

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

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.

Weekly Installs

Repository

atxp-dev/cli

GitHub Stars

First Seen

Feb 22, 2026

Security Audits

Gen Agent Trust HubFail SocketWarn SnykWarn

Installed on

openclaw61

trae-cn61

pochi61

neovate61

droid61

codex61