Memstate AI

Versioned, structured memory for AI agents. Every fact is tracked, every change is logged, and your agent always gets the current answer — not a pile of outd...

Security Scan

The skill's code, instructions, and requested secret (MEMSTATE_API_KEY) align with a Memstate REST API client: nothing requests unrelated credentials or installs unexpected software.

Purpose & Capability

Name/description, required binary (python3), and the single required env var (MEMSTATE_API_KEY) match the included scripts that call https://api.memstate.ai. No unrelated credentials or binaries are requested.

Instruction Scope

SKILL.md instructs the agent to run the bundled Python scripts to search, get, set, ingest, view history, and soft-delete memories. The instructions reference only the included scripts, project/keypath parameters, and the MEMSTATE_API_KEY; they do not direct the agent to read unrelated files or exfiltrate data to unexpected endpoints.

Install Mechanism

No install spec or external downloads are present; this is instruction-only with included Python scripts. Nothing in the manifest downloads or writes third-party code during install.

Credentials

Only MEMSTATE_API_KEY is required and is used exclusively as an X-API-Key header to api.memstate.ai. This is proportionate for a remote API client, but be aware the key will be sent to a third-party service and grants whatever privileges the key provides.

Persistence & Privilege

always is false (no forced global presence). The skill can be invoked autonomously by the agent (default behavior) — normal for skills — which means an agent could call the remote API using your MEMSTATE_API_KEY without further prompts if allowed by your agent configuration.

Assessment

This skill is a straightforward Python client for the Memstate API and only needs MEMSTATE_API_KEY and python3. Before installing: 1) Ensure you trust memstate.ai because your API key and any memories will be sent to api.memstate.ai. 2) Use a least-privilege API key (not a broadly privileged or reused secret) so compromised keys are limited. 3) Remember the agent may call the scripts autonomously — review agent invocation settings if you want to require manual approval. 4) You can inspect the included Python scripts (they are plain and readable) to confirm no additional behavior. Revoke/rotate the key if you stop using the skill or suspect misuse.

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

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

Markdown (preferred for task summaries)

## 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.

# 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)

# 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

# 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.

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.

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

# 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.

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.

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.

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

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:

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