Memstate AI Memory Management
This skill provides a full-featured alternative to the Memstate MCP plugin by
interacting directly with the Memstate REST API. It gives agents a persistent,
structured, and versioned knowledge base with conflict detection, semantic
search, and full version history.
Core Concepts
| Concept | Description |
|---|
| Project | Top-level container for memories (e.g., myapp, backend-api). Auto-created on first write. |
| Keypath |
Dot-separated hierarchical path (e.g.,
auth.method). Auto-prefixed with
project.{project_id}. |
|
Memory | A single fact or markdown summary stored at a keypath with full version history. |
|
Versioning | Writing to an existing keypath supersedes the old value. History is always preserved. |
|
Tombstone | Deleting a keypath creates a tombstone version — history is never destroyed. |
Input Formats
Direct keypath = value assignment
CODEBLOCK0
Markdown (preferred for task summaries)
CODEBLOCK1
Workflows
Before Starting a Task (Recall)
Always check what already exists before making decisions or modifying code.
CODEBLOCK2
After Completing a Task (Remember)
CODEBLOCK3
Manage History and Cleanup
CODEBLOCK4
Script Reference
memstate_set.py — Set a single keypath value
Stores one fact at a specific keypath. Synchronous, immediately available.
Supersedes the previous value if the keypath already exists.
CODEBLOCK5
Response keys: action (created|superseded), memory_id, version
memstate_remember.py — Ingest markdown or text
Preferred for task summaries, meeting notes, or any multi-fact content.
The AI engine automatically extracts structured keypaths from your text.
Processing is async (~15–18 s); the script polls until completion.
CODEBLOCK6
Response keys: status (completed|failed), job_id, memories_created
memstate_get.py — Browse and retrieve memories
CODEBLOCK7
Response keys (project tree): domains, total_memories
Response keys (subtree): memories, total_count
Response keys (list projects): projects
memstate_search.py — Semantic search
Find memories by meaning when you don't know the exact keypath.
CODEBLOCK8
Response keys: results (array), total_found, query
memstate_history.py — Version history
View all versions of a keypath or memory chain.
CODEBLOCK9
Response keys: versions (array), total_versions
memstate_delete.py — Soft-delete a keypath
Creates a tombstone version. History is always preserved.
CODEBLOCK10
Response keys: deleted_count, deleted_keypaths
memstate_delete_project.py — Soft-delete a project
CODEBLOCK11
Response keys: project_id, deleted_count
Best Practices
- 1. One keypath = one fact. Use
api.style not api. Be specific. - Update, don't duplicate. When a fact changes, call
memstate_set.py with the SAME keypath and the NEW value. Do not create a new keypath. - Trust
is_latest: true. Search results may show multiple versions. Only trust results where is_latest is true. - Use Markdown for summaries.
memstate_remember.py excels at parsing Markdown lists, headings, and key-value pairs into structured keypaths. - Search before browsing.
memstate_search.py is faster than browsing the tree when you know what you're looking for. - Use categories. Setting
--category decision on architecture choices makes them easier to filter later.
Authentication
Set the MEMSTATE_API_KEY environment variable before running any script:
CODEBLOCK12
Get your API key at https://memstate.ai/dashboard.
Resources
Memstate AI 内存管理
此技能通过直接与Memstate REST API交互，提供Memstate MCP插件的全功能替代方案。它为智能体提供持久化、结构化且带版本控制的知识库，具备冲突检测、语义搜索和完整版本历史功能。
核心概念
| 概念 | 描述 |
|---|
| 项目 | 记忆的顶级容器（例如 myapp、backend-api）。首次写入时自动创建。 |
| 键路径 |
点分隔的层级路径（例如 auth.method）。自动添加 project.{project_id}. 前缀。 |
|
记忆 | 存储在键路径上的单个事实或Markdown摘要，包含完整版本历史。 |
|
版本控制 | 写入现有键路径会取代旧值。历史记录始终保留。 |
|
墓碑标记 | 删除键路径会创建一个墓碑版本——历史记录永远不会被销毁。 |
输入格式
直接键路径 = 值赋值
config.port = 8080
database.engine = PostgreSQL 16
auth.method = 带httpOnly cookie的JWT
status.deployment = production
Markdown（推荐用于任务摘要）
markdown
架构决策
- - 数据库：PostgreSQL 16
- 认证：带httpOnly cookie的JWT
- 部署：AWS ECS上的Docker
- API风格：带OpenAPI 3.1的REST
工作流程
开始任务前（回忆）
在做出决策或修改代码前，始终检查已存在的内容。
bash
1. 语义搜索——通过含义查找相关事实
python3 {baseDir}/scripts/memstate_search.py \
--project myapp \
--query 认证是如何配置的
2. 浏览完整项目树（所有域和键路径）
python3 {baseDir}/scripts/memstate_get.py \
--project myapp
3. 获取包含完整内容的特定子树
python3 {baseDir}/scripts/memstate_get.py \
--project myapp --keypath database --include-content
完成任务后（记忆）
bash
存储单个事实（配置、状态、版本号）
python3 {baseDir}/scripts/memstate_set.py \
--project myapp \
--keypath config.port \
--value 8080 \
--category fact
存储丰富的Markdown摘要（AI自动提取键路径）
python3 {baseDir}/scripts/memstate_remember.py \
--project myapp \
--content ## 认证迁移\n- 从JWT改为服务器端会话\n- 通过TOTP添加MFA\n- 文件：auth.go, middleware.go \
--source agent
管理历史和清理
bash
查看事实随时间的变化
python3 {baseDir}/scripts/memstate_history.py \
--project myapp --keypath database.engine
软删除过时的键路径（历史记录保留）
python3 {baseDir}/scripts/memstate_delete.py \
--project myapp --keypath config.old_setting
软删除整个项目
python3 {baseDir}/scripts/memstate
deleteproject.py \
--project myapp
脚本参考
memstate_set.py — 设置单个键路径值
在特定键路径存储一个事实。同步操作，立即可用。
如果键路径已存在，则取代之前的值。
bash
python3 {baseDir}/scripts/memstate_set.py \
--project PROJECT_ID \
--keypath KEYPATH \
--value VALUE \
[--category CATEGORY] # decision | fact | config | requirement | note | code | learning
[--topics TAG1,TAG2]
响应键： action（created|superseded）、memory_id、version
memstate_remember.py — 摄取Markdown或文本
推荐用于任务摘要、会议记录或任何多事实内容。
AI引擎会自动从文本中提取结构化键路径。
处理为异步操作（约15-18秒）；脚本会轮询直到完成。
bash
python3 {baseDir}/scripts/memstate_remember.py \
--project PROJECT_ID \
--content MARKDOWNORTEXT \
[--source agent|readme|docs|meeting|code] \
[--context 用于提取的可选提示]
响应键： status（completed|failed）、jobid、memoriescreated
memstate_get.py — 浏览和检索记忆
bash
列出所有项目
python3 {baseDir}/scripts/memstate_get.py
完整项目树（返回域和键路径）
python3 {baseDir}/scripts/memstate
get.py --project PROJECTID
键路径处的子树
python3 {baseDir}/scripts/memstate_get.py \
--project PROJECT_ID --keypath KEYPATH [--include-content] [--at-revision N]
按UUID获取单个记忆
python3 {baseDir}/scripts/memstate_get.py --memory-id UUID
响应键（项目树）： domains、total_memories
响应键（子树）： memories、total_count
响应键（列出项目）： projects
memstate_search.py — 语义搜索
当不知道确切键路径时，通过含义查找记忆。
bash
python3 {baseDir}/scripts/memstate_search.py \
--query 自然语言查询 \
[--project PROJECT_ID] \
[--limit N] # 默认20，最大100
响应键： results（数组）、total_found、query
memstate_history.py — 版本历史
查看键路径或记忆链的所有版本。
bash
python3 {baseDir}/scripts/memstate_history.py \
--project PROJECT_ID --keypath KEYPATH
或
python3 {baseDir}/scripts/memstate_history.py \
--memory-id UUID
响应键： versions（数组）、total_versions
memstate_delete.py — 软删除键路径
创建墓碑版本。历史记录始终保留。
bash
python3 {baseDir}/scripts/memstate_delete.py \
--project PROJECT_ID \
--keypath KEYPATH \
[--recursive] # 删除整个子树
响应键： deletedcount、deletedkeypaths
memstatedeleteproject.py — 软删除项目
bash
python3 {baseDir}/scripts/memstatedeleteproject.py \
--project PROJECT_ID
响应键： projectid、deletedcount
最佳实践
- 1. 一个键路径 = 一个事实。 使用 api.style 而不是 api。要具体。
- 更新，不要重复。 当事实发生变化时，使用相同的键路径和新值调用 memstateset.py。不要创建新的键路径。
- 信任 islatest: true。 搜索结果可能显示多个版本。只信任 islatest 为 true 的结果。
- 使用Markdown编写摘要。 memstateremember.py 擅长将Markdown列表、标题和键值对解析为结构化键路径。
- 先搜索再浏览。 当你知道要找什么时，memstate_search.py 比浏览树更快。
- 使用分类。 在架构选择上设置 --category decision 使其以后更容易筛选。
身份认证
在运行任何脚本之前设置 MEMSTATEAPIKEY 环境变量：
bash
export MEMSTATEAPIKEY=你的API密钥
在 https://memstate.ai/dashboard 获取你的API密钥。
资源
