Agent Imprint Documentation

Welcome to the Agent Imprint API documentation. This guide covers everything you need to integrate persistent memory capabilities into your AI agents.

The Agent Imprint API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

The Agent Imprint API uses API keys to authenticate requests. You can create and manage your API keys after creating an organization.

Authorization: Bearer your-api-key-here

Quickstart

Get up and running with Agent Imprint in just a few minutes. This guide will walk you through creating an organization, generating an API key, creating an agent, and storing your first memory.

{
  "name": "My Organization",
  "tier": "free"
}

{
  "name": "Production Key",
  "permissions": ["read", "write"]
}

{
  "name": "My Assistant",
  "model": "gpt-4",
  "metadata": {
    "version": "1.0.0",
    "purpose": "customer-support"
  }
}

{
  "name": "conversation-memory",
  "agent_uuid": "agent-uuid-here"
}

{
  "type": "conversation",
  "content": {
    "summary": "User prefers dark mode and concise responses",
    "preferences": {
      "theme": "dark",
      "verbosity": "low"
    }
  },
  "metadata": {
    "source": "chat-session-123"
  }
}

TypeScript SDK Installation

The official TypeScript SDK provides a convenient way to interact with the Agent Imprint API.

npm install @agentimprint/sdk

pnpm add @agentimprint/sdk

SDK Basic Usage

Here's a complete example of using the TypeScript SDK to create vaults and store memories.

import { AgentImprint, ImprintML } from '@agentimprint/sdk';

// Initialize the client
const imprint = new AgentImprint({
  apiKey: process.env.AGENT_IMPRINT_API_KEY,
  baseUrl: 'https://agentimprint.ai/api/v1'
});

// Create or retrieve an agent
const agent = await imprint.agents.create({
  name: 'My Assistant',
  model: 'claude-3-sonnet'
});

// Create a vault for the agent
const vault = await imprint.vaults.create({
  name: 'user-preferences',
  agentUuid: agent.uuid
});

// Store a memory entry with ImprintML validation
const entry = await vault.entries.create({
  type: 'preference',
  content: ImprintML.preference({
    category: 'communication',
    value: { style: 'formal', language: 'en' }
  }),
  tags: ['user-settings']
});

// Retrieve entries with filtering
const entries = await vault.entries.list({
  type: 'preference',
  limit: 10
});

// Search across vaults
const results = await imprint.search({
  query: 'user preferences',
  filters: { type: 'preference' }
});

// Verify vault integrity
const proof = await vault.getMerkleProof(entry.uuid);
const isValid = await vault.verifyIntegrity();

Organizations

Organizations are the top-level container for agents, vaults, and API keys.

{
  "name": "string (required)",
  "tier": "free | pro | enterprise (default: free)"
}

{
  "uuid": "org-uuid",
  "name": "My Organization",
  "tier": "free",
  "api_key": "ai_xxxxxxxxxxxx",
  "created_at": "2024-01-01T00:00:00Z"
}

{
  "uuid": "org-uuid",
  "name": "My Organization",
  "tier": "pro",
  "agents_count": 5,
  "vaults_count": 12,
  "created_at": "2024-01-01T00:00:00Z"
}

Agents

Agents represent AI instances that have persistent memory. Each agent has a unique Ed25519 fingerprint for cryptographic identity verification.

{
  "name": "string (required)",
  "model": "string (optional)",
  "metadata": "object (optional)"
}

{
  "uuid": "agent-uuid",
  "name": "My Assistant",
  "model": "gpt-4",
  "fingerprint": "SHA256:xxxxx...",
  "public_key": "-----BEGIN PUBLIC KEY-----...",
  "metadata": {},
  "created_at": "2024-01-01T00:00:00Z"
}

Vaults

Vaults are encrypted containers for memory entries. Each vault is associated with an agent and uses AES-256-GCM encryption.

{
  "name": "string (required)",
  "agent_uuid": "string (required)",
  "description": "string (optional)"
}

Vault Entries

Entries are individual memory records stored in vaults. All entries are validated against the ImprintML schema and encrypted at rest.

{
  "type": "string (required: conversation|preference|fact|event|relationship)",
  "content": "object (required)",
  "tags": "array (optional)",
  "metadata": "object (optional)"
}

{
  "uuid": "entry-uuid",
  "type": "conversation",
  "content": { ... },
  "tags": ["user-settings"],
  "checksum": "sha256:xxxx...",
  "created_at": "2024-01-01T00:00:00Z"
}

{
  "entries": [
    { "type": "fact", "content": { ... } },
    { "type": "preference", "content": { ... } }
  ]
}

Discovery

The discovery API enables cross-vault and cross-organization memory discovery while respecting privacy settings.

{
  "found": true,
  "agent": {
    "uuid": "agent-uuid",
    "name": "My Assistant",
    "fingerprint": "SHA256:xxxxx...",
    "public_key": "-----BEGIN PUBLIC KEY-----..."
  },
  "vaults": [
    { "uuid": "vault-uuid", "name": "public-memory", "entry_count": 42 }
  ]
}

{
  "query": "string (required)",
  "filters": {
    "type": "string (optional)",
    "tags": "array (optional)",
    "vault_uuid": "string (optional)",
    "since": "ISO 8601 timestamp (optional)"
  },
  "limit": "number (default: 20, max: 100)"
}

Integrity & Merkle Trees

Agent Imprint uses Merkle trees to provide tamper-proof audit logs. Every vault has a Merkle root that changes when entries are added or modified.

{
  "root": "sha256:xxxx...",
  "leaf_count": 42,
  "depth": 6,
  "computed_at": "2024-01-01T00:00:00Z"
}

{
  "entry_hash": "sha256:xxxx...",
  "proof": [
    { "position": "left", "hash": "sha256:yyyy..." },
    { "position": "right", "hash": "sha256:zzzz..." }
  ],
  "root": "sha256:xxxx..."
}

{
  "valid": true,
  "entries_verified": 42,
  "computed_root": "sha256:xxxx...",
  "stored_root": "sha256:xxxx...",
  "verified_at": "2024-01-01T00:00:00Z"
}

Error Codes

Agent Imprint uses conventional HTTP response codes to indicate the success or failure of an API request.

{
  "error": {
    "code": "validation_error",
    "message": "The given data was invalid.",
    "errors": {
      "name": ["The name field is required."],
      "type": ["The selected type is invalid."]
    },
    "request_id": "req_xxxxx"
  }
}

Rate Limiting

API requests are rate limited based on your organization's tier. Rate limits are applied per API key.

Rate Limit Headers

Each response includes headers indicating your current rate limit status: