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#

ConceptDescriptionProjectTop-level container for memories (e.g., myapp, backend-api). Auto-created on first write.KeypathDot-separated hierarchical path (e.g., auth.method). Auto-prefixed with project.{project_id}.MemoryA single fact or markdown summary stored at a keypath with full version history.VersioningWriting to an existing keypath supersedes the old value. History is always preserved.TombstoneDeleting a keypath creates a tombstone version — history is never destroyed.

Input Formats#

Direct keypath = value assignment#

text

config.port = 8080
database.engine = PostgreSQL 16
auth.method = JWT with httpOnly cookies
status.deployment = production

Markdown (preferred for task summaries)#

markdown

## Architecture Decision
- Database: PostgreSQL 16
- Auth: JWT with httpOnly cookies
- Deploy: Docker on AWS ECS
- API style: REST with OpenAPI 3.1

Workflows#

Before Starting a Task (Recall)#

Always check what already exists before making decisions or modifying code.

bash

# 1. Semantic search — find relevant facts by meaning
python3 {baseDir}/scripts/memstate_search.py \
  --project "myapp" \
  --query "how is authentication configured"

# 2. Browse the full project tree (all domains and keypaths)
python3 {baseDir}/scripts/memstate_get.py \
  --project "myapp"

# 3. Get a specific subtree with full content
python3 {baseDir}/scripts/memstate_get.py \
  --project "myapp" --keypath "database" --include-content

After Completing a Task (Remember)#

bash

# Store a single fact (config, status, version numbers)
python3 {baseDir}/scripts/memstate_set.py \
  --project "myapp" \
  --keypath "config.port" \
  --value "8080" \
  --category "fact"

# Store a rich markdown summary (AI extracts keypaths automatically)
python3 {baseDir}/scripts/memstate_remember.py \
  --project "myapp" \
  --content "## Auth Migration\n- Changed from JWT to server-side sessions\n- Added MFA via TOTP\n- Files: auth.go, middleware.go" \
  --source "agent"

Manage History and Cleanup#

bash

# View how a fact changed over time
python3 {baseDir}/scripts/memstate_history.py \
  --project "myapp" --keypath "database.engine"

# Soft-delete an outdated keypath (history preserved)
python3 {baseDir}/scripts/memstate_delete.py \
  --project "myapp" --keypath "config.old_setting"

# Soft-delete an entire project
python3 {baseDir}/scripts/memstate_delete_project.py \
  --project "myapp"

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.

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]

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.

bash

python3 {baseDir}/scripts/memstate_remember.py \
  --project PROJECT_ID \
  --content "MARKDOWN_OR_TEXT" \
  [--source agent|readme|docs|meeting|code] \
  [--context "optional hint for extraction"]

Response keys: status (completed|failed), job_id, memories_created

---

memstate_get.py — Browse and retrieve memories#

bash

# List all projects
python3 {baseDir}/scripts/memstate_get.py

# Full project tree (returns domains and keypaths)
python3 {baseDir}/scripts/memstate_get.py --project PROJECT_ID

# Subtree at a keypath
python3 {baseDir}/scripts/memstate_get.py \
  --project PROJECT_ID --keypath KEYPATH [--include-content] [--at-revision N]

# Single memory by UUID
python3 {baseDir}/scripts/memstate_get.py --memory-id UUID

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.

bash

python3 {baseDir}/scripts/memstate_search.py \
  --query "NATURAL_LANGUAGE_QUERY" \
  [--project PROJECT_ID] \
  [--limit N]  # default 20, max 100

Response keys: results (array), total_found, query

---

memstate_history.py — Version history#

View all versions of a keypath or memory chain.

bash

python3 {baseDir}/scripts/memstate_history.py \
  --project PROJECT_ID --keypath KEYPATH
# or
python3 {baseDir}/scripts/memstate_history.py \
  --memory-id UUID

Response keys: versions (array), total_versions

---

memstate_delete.py — Soft-delete a keypath#

Creates a tombstone version. History is always preserved.

bash

python3 {baseDir}/scripts/memstate_delete.py \
  --project PROJECT_ID \
  --keypath KEYPATH \
  [--recursive]  # delete entire subtree

Response keys: deleted_count, deleted_keypaths

---

memstate_delete_project.py — Soft-delete a project#

bash

python3 {baseDir}/scripts/memstate_delete_project.py \
  --project PROJECT_ID

Response keys: project_id, deleted_count

---

Best Practices#

1. One keypath = one fact. Use api.style not api. Be specific.
2. 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.
3. Trust is_latest: true. Search results may show multiple versions. Only trust results where is_latest is true.
4. Use Markdown for summaries. memstate_remember.py excels at parsing Markdown lists, headings, and key-value pairs into structured keypaths.
5. Search before browsing. memstate_search.py is faster than browsing the tree when you know what you're looking for.
6. 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:

bash

export MEMSTATE_API_KEY="your_api_key_here"

Get your API key at https://memstate.ai/dashboard.

Resources#

• Documentation: https://memstate.ai/docs
• MCP Plugin (alternative): https://github.com/memstate-ai/memstate-mcp
• Benchmark: https://github.com/memstate-ai/memstate-benchmark