Guia de Validação

Usando o SDK PAM (recomendado)

O SDK oficial Python é a forma recomendada de validar arquivos PAM. Ele realiza validação profunda além da conformidade de schema.

Instalação

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

CLI

# Validar um arquivo PAM individual (schema + verificações profundas)
pam validate memory-store.json

# Validar um diretório bundle PAM inteiro
pam validate ./my-pam-bundle/

# Validação apenas de schema (pular verificações profundas)
pam validate memory-store.json --no-deep

API programática

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("Arquivo não encontrado")
except PAMSchemaError as e:
    print(f"Não é um arquivo PAM válido: {e}")
except PAMValidationError as e:
    print(f"Validação de schema falhou: {e}")
else:
    result = validate_memory_store(store)

    if result.is_valid:
        print(f"Válido — {len(store.memories)} memórias")
    else:
        for issue in result.errors:
            print(issue)
    for issue in result.warnings:
        print(issue)

O que o SDK valida

O SDK vai além da conformidade de schema. Quando você executa pam validate (ou chama validate_memory_store()), ele verifica:

• Content hashes — Recalcula o content_hash de cada memória e compara com o valor declarado. Se o conteúdo foi modificado após a geração do hash, a validação falha.
• Bloco de integridade — Verifica que total_memories corresponde à contagem real e que o checksum agregado está correto.
• Referências cruzadas — Garante que os campos from/to das relações, conversation_ref, superseded_by e derived_memories apontam para objetos que realmente existem no documento.
• Ordenação temporal — Verifica que created_at ≤ updated_at e valid_from ≤ valid_until. Também sinaliza casos como last_reinforced anterior a created_at.
• Unicidade de IDs — Sem IDs duplicados entre memórias, relações ou entradas do índice de conversas.
• Regras de tipo custom — type='custom' exige um campo custom_type (e vice-versa).
• Consistência de status — Uma memória com status superseded deve ter superseded_by definido, e vice-versa.
• DAG de conversas — Para arquivos de conversa, verifica que parent_id e children_ids formam uma árvore consistente.

Erros causam falha na validação. Warnings são informativos e não afetam is_valid.

Validar conversas e embeddings

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

# Validação de conversa (verifica DAG de mensagens)
conv = load_conversation("conversations/conv-001.json")
result = validate_conversation(conv)

# Validação de embeddings (verifica dimensões, IDs)
# Opcionalmente passe o memory store para verificações de referência cruzada
embeddings = load_embeddings("embeddings.json")
store = load_memory_store("memory-store.json")
result = validate_embeddings(embeddings, memory_store=store)

---

Validação manual (sem o SDK)

Se você precisa validar em uma linguagem ainda não coberta por um SDK oficial, pode usar qualquer validador JSON Schema Draft 2020-12 diretamente. A validação manual verifica apenas conformidade de schema — não verifica content hashes, referências cruzadas ou consistência temporal.

Baixar os schemas

# Obrigatório
curl -O https://portable-ai-memory.org/schemas/portable-ai-memory.schema.json

# Opcional (para arquivos de conversas e embeddings)
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

Você deve importar de ajv/dist/2020.js, e não o export padrão ajv. O padrão assume Draft-07 e rejeitará arquivos PAM válidos.

O mesmo padrão se aplica a arquivos de conversa e embeddings — substitua o nome do arquivo de schema e o nome do arquivo de entrada:

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

Exemplos de saída

Sucesso:

memory-store.json valid

Erro:

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