Validation Guide

Using the PAM SDK (recommended)

The official Python SDK is the recommended way to validate PAM files. It performs deep validation beyond schema compliance.

Install

pip install 'portable-ai-memory[cli]'

CLI

# Validate a single PAM file (schema + deep checks)
pam validate memory-store.json

# Validate an entire PAM bundle directory
pam validate ./my-pam-bundle/

# Schema-only validation (skip deep checks)
pam validate memory-store.json --no-deep

Programmatic API

from portable_ai_memory import load, validate_memory_store
from portable_ai_memory import PAMSchemaError, PAMValidationError

try:
    store = load("memory-store.json")
except FileNotFoundError:
    print("File not found")
except PAMSchemaError as e:
    print(f"Not a valid PAM file: {e}")
except PAMValidationError as e:
    print(f"Schema validation failed: {e}")
else:
    result = validate_memory_store(store)

    if result.is_valid:
        print(f"Valid — {len(store.memories)} memories")
    else:
        for issue in result.errors:
            print(issue)
    for issue in result.warnings:
        print(issue)

What the SDK validates

The SDK goes beyond schema compliance. When you run pam validate (or call validate_memory_store()), it checks:

• Content hashes — Recomputes each memory’s content_hash and compares it to the declared value. If the content was modified after the hash was generated, validation fails.
• Integrity block — Verifies that total_memories matches the actual count and that the aggregate checksum is correct.
• Cross-references — Ensures that relation from/to fields, conversation_ref, superseded_by, and derived_memories all point to objects that actually exist in the document.
• Temporal ordering — Checks that created_at ≤ updated_at and valid_from ≤ valid_until. Also flags cases like last_reinforced before created_at.
• ID uniqueness — No duplicate IDs across memories, relations, or conversation index entries.
• Custom type rules — type='custom' requires a custom_type field (and vice versa).
• Status consistency — A memory with status superseded should have superseded_by set, and vice versa.
• Conversation DAG — For conversation files, verifies that parent_id and children_ids form a consistent tree.

Errors cause validation to fail. Warnings are informational and don’t affect is_valid.

Validating conversations and embeddings

from portable_ai_memory import load_conversation, load_embeddings, load_memory_store
from portable_ai_memory import validate_conversation, validate_embeddings

# Conversation validation (checks message DAG)
conv = load_conversation("conversations/conv-001.json")
result = validate_conversation(conv)

# Embeddings validation (checks dimensions, IDs)
# Optionally pass the memory store for cross-reference checks
embeddings = load_embeddings("embeddings.json")
store = load_memory_store("memory-store.json")
result = validate_embeddings(embeddings, memory_store=store)

---

Manual validation (without the SDK)

If you need to validate in a language not yet covered by an official SDK, you can use any JSON Schema Draft 2020-12 validator directly. Manual validation only checks schema compliance — it does not verify content hashes, cross-references, or temporal consistency.

Download the schemas

# Required
curl -O https://portable-ai-memory.org/schemas/portable-ai-memory.schema.json

# Optional (for conversation and embeddings files)
curl -O https://portable-ai-memory.org/schemas/portable-ai-memory-conversation.schema.json
curl -O https://portable-ai-memory.org/schemas/portable-ai-memory-embeddings.schema.json

Memory store

Python (jsonschema)

pip install jsonschema

from jsonschema import Draft202012Validator
import json, sys

with open("portable-ai-memory.schema.json") as f:
    schema = json.load(f)
with open("memory-store.json") as f:
    data = json.load(f)
errors = sorted(
    Draft202012Validator(schema).iter_errors(data),
    key=lambda e: list(e.path),
)

if not errors:
    print("memory-store.json valid")
else:
    print("memory-store.json invalid")
    for e in errors:
        path = "/".join(str(p) for p in e.path) or "(root)"
        print(f"  {path}: {e.message}")
    sys.exit(1)

Node.js (ajv)

npm install ajv ajv-formats

import Ajv2020 from "ajv/dist/2020.js";
import addFormats from "ajv-formats";
import {readFileSync} from "node:fs";

const ajv = new Ajv2020({allErrors: true});
addFormats(ajv);
const schema = JSON.parse(readFileSync("portable-ai-memory.schema.json", "utf8"));
const data = JSON.parse(readFileSync("memory-store.json", "utf8"));

const validate = ajv.compile(schema);
if (validate(data)) {
  console.log("memory-store.json valid");
} else {
  console.log("memory-store.json invalid");
  for (const err of validate.errors) {
    console.log(`  ${err.instancePath || "(root)"}: ${err.message}`);
  }
  process.exit(1);
}

Draft 2020-12

You must import from ajv/dist/2020.js, not the default ajv export. The default assumes Draft-07 and will reject valid PAM files.

The same pattern applies to conversation and embeddings files — replace the schema filename and input filename accordingly:

• Conversations: portable-ai-memory-conversation.schema.json
• Embeddings: portable-ai-memory-embeddings.schema.json

Output examples

Success:

memory-store.json valid

Error:

memory-store.json invalid
  memories/0: must have required property 'content_hash'