### Install SDK

Source: https://docs.atomicstrata.ai/sdk/quickstart

Install the Atomic Memory SDK using npm, pnpm, or yarn.

```bash
npm install @atomicmemory/sdk
```

--------------------------------

### Hook Installation and Execution Commands

Source: https://docs.atomicstrata.ai/cli

Commands for installing and running lifecycle hooks for different hosts and runtimes.

```bash
atomicmemory hooks install --host codex --runtime node
atomicmemory hooks install --host codex --runtime python
atomicmemory hooks run user-prompt-submit --host codex
```

--------------------------------

### Install OpenClaw Plugin from Local Checkout

Source: https://docs.atomicstrata.ai/integrations/coding-agents/openclaw/local

For local development, clone the repository, install dependencies, build the plugin, and then install it into OpenClaw. This allows for testing changes directly.

```bash
git clone https://github.com/atomicstrata/atomicmemory-integrations.git
cd atomicmemory-integrations
pnpm install
pnpm --filter @atomicmemory/openclaw-plugin build
openclaw plugins install -l ./plugins/openclaw
```

--------------------------------

### Hook Installation for Different Runtimes

Source: https://docs.atomicstrata.ai/cli

Demonstrates installing hooks for Codex with Node.js and Python runtimes, and for Claude Code with Node.js.

```bash
atomicmemory hooks install --host codex --runtime node
atomicmemory hooks install --host codex --runtime python
atomicmemory hooks install --host claude-code --runtime node
```

--------------------------------

### Install and Initialize AtomicMemory CLI

Source: https://docs.atomicstrata.ai/quickstart

Installs the AtomicMemory CLI globally and initializes it for a local profile, configuring connection details and saving the API key.

```bash
npm install -g @atomicmemory/cli

printf '%s\n' 'local-dev-key' | \
atomicmemory init \
  --profile local \
  --provider atomicmemory \
  --api-url http://127.0.0.1:3050 \
  --trust-surface local \
  --user "$USER" \
  --namespace quickstart \
  --api-key-stdin \
  --save-api-key
```

--------------------------------

### Install AtomicMemory Vercel AI Adapter

Source: https://docs.atomicstrata.ai/integrations/frameworks/vercel-ai-sdk/local

Install the necessary packages for the AtomicMemory Vercel AI adapter and the core SDK using npm.

```bash
npm install @atomicmemory/vercel-ai @atomicmemory/sdk
```

--------------------------------

### Install Claude Code Plugin

Source: https://docs.atomicstrata.ai/integrations/coding-agents/claude-code/local

Install the AtomicMemory integrations for Claude Code from the marketplace and then install the Claude Code plugin itself.

```bash
claude plugin marketplace add atomicstrata/atomicmemory-integrations
claude plugin install claude-code@atomicmemory
```

--------------------------------

### Install OpenAI Agents and AtomicMemory SDK

Source: https://docs.atomicstrata.ai/integrations/frameworks/openai-agents/local

Install the necessary npm packages for the OpenAI Agents SDK and the AtomicMemory SDK.

```bash
npm install @atomicmemory/openai-agents @atomicmemory/sdk
```

--------------------------------

### Install and Run AtomicMemory CLI

Source: https://docs.atomicstrata.ai/cli

Installs the AtomicMemory CLI globally using npm and then runs the interactive terminal dashboard. Memory operations require a configured backend.

```bash
npm install -g @atomicmemory/cli
atomicmemory
```

--------------------------------

### Provider-Backed Command with Overrides

Source: https://docs.atomicstrata.ai/cli

Example of using the search command with explicit provider and scope overrides.

```bash
atomicmemory search "release policy" \
  --provider atomicmemory \
  --api-url http://127.0.0.1:3050 \
  --trust-surface local \
  --user "$USER" \
  --namespace atomicmemory-integrations
```

--------------------------------

### Install Hermes AtomicMemory Plugin

Source: https://docs.atomicstrata.ai/integrations/coding-agents/hermes/local

Install the Hermes plugin for AtomicMemory using npx. This command ensures the necessary components are available for integration.

```bash
npx -y @atomicmemory/hermes-plugin install
```

--------------------------------

### Initialize Local Development Profile

Source: https://docs.atomicstrata.ai/cli

Create a named local profile for Docker quickstart. Use `--api-key-stdin` to securely pass the API key and `--save-api-key` to persist it.

```bash
printf '%s\n' 'local-dev-key' | \
  atomicmemory init \
  --profile local \
  --provider atomicmemory \
  --api-url http://127.0.0.1:3050 \
  --trust-surface local \
  --user "$USER" \
  --namespace my-project \
  --api-key-stdin \
  --save-api-key
```

--------------------------------

### Install Hermes Provider from Source Checkout

Source: https://docs.atomicstrata.ai/integrations/coding-agents/hermes/local

For local development, clone the AtomicMemory integrations repository and link the Hermes provider into the Hermes plugin directory.

```bash
git clone https://github.com/atomicstrata/atomicmemory-integrations.git
cd atomicmemory-integrations

mkdir -p "$HERMES_HOME/plugins/memory"
ln -s "$(pwd)/plugins/hermes" "$HERMES_HOME/plugins/memory/atomicmemory"
```

--------------------------------

### Interactive Mode Command Example

Source: https://docs.atomicstrata.ai/cli

Example of a command typed directly into the interactive mode prompt when scope is not configured. This includes necessary flags for provider, API URL, trust surface, and user.

```text
status --provider atomicmemory --api-url http://127.0.0.1:3050 --trust-surface local --user alice
```

--------------------------------

### Contributor Setup for Atomic Memory Core

Source: https://docs.atomicstrata.ai/quickstart

Clone the repository and set up the local development environment using Docker Compose. Ensure to configure your API key in the .env file.

```bash
git clone https://github.com/atomicstrata/atomicmemory-core.git
cd atomicmemory-core
cp .env.example .env
# edit .env, set OPENAI_API_KEY
docker compose up -d --build
```

--------------------------------

### Start Claude Code

Source: https://docs.atomicstrata.ai/integrations/coding-agents/claude-code/local

Start the Claude Code application. The plugin will automatically start the local AtomicMemory runtime and expose memory tools.

```bash
claude
```

--------------------------------

### Install OpenClaw AtomicMemory Plugin

Source: https://docs.atomicstrata.ai/integrations/coding-agents/openclaw/local

Install the OpenClaw plugin for AtomicMemory integration. This command adds the necessary components to your OpenClaw environment.

```bash
openclaw plugins install @atomicmemory/openclaw-plugin
```

--------------------------------

### Express.js Example for Memory Ingestion and Search

Source: https://docs.atomicstrata.ai/sdk/guides/nodejs-server

This Express.js server example demonstrates how to use MemoryClient to ingest text content and perform searches. It assumes authentication is handled at the HTTP layer, and the derived `userId` is passed to the SDK.

```typescript
import express from 'express';
import { MemoryClient } from '@atomicmemory/sdk';

const memory = new MemoryClient({ 
  providers: { atomicmemory: { apiUrl: process.env.CORE_URL! } }, 
});
await memory.initialize();

const app = express();
app.use(express.json());

app.post('/memory', async (req, res) => {
  const { userId, content } = req.body;
  await memory.ingest({
    mode: 'text',
    content,
    scope: { user: userId },
    provenance: { source: 'api' },
  });
  res.status(204).end();
});

app.get('/memory/:userId/search', async (req, res) => {
  const page = await memory.search({
    query: req.query.q as string,
    scope: { user: req.params.userId },
    limit: 10,
  });
  res.json(page);
});

app.listen(3000);
```

--------------------------------

### Run AtomicMemory CLI without Global Install

Source: https://docs.atomicstrata.ai/cli

Executes the AtomicMemory CLI using `npx` without requiring a global installation. This is useful for trying out the CLI temporarily.

```bash
npx -y @atomicmemory/cli
```

--------------------------------

### Install Hermes Provider via Python Package

Source: https://docs.atomicstrata.ai/integrations/coding-agents/hermes/local

Install the AtomicMemory Hermes provider into the Hermes virtual environment using pip. This method is for teams managing Hermes with Python packages.

```bash
uv pip install atomicmemory-hermes \
  --python "$HOME/.hermes/hermes-agent/venv/bin/python"
```

--------------------------------

### Running Core Service with Docker

Source: https://docs.atomicstrata.ai/platform/consuming-core

Deploy and run the Atomic Strata core service using a Docker container. This example demonstrates setting an OpenAI API key and mounting a volume for persistent storage. Use `docker logs -f` to monitor startup.

```bash
export OPENAI_API_KEY="sk-..."

docker run -d --pull always \
  --name atomicmemory-core \
  -p 127.0.0.1:3050:3050 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -v $HOME/.atomicstrata/atomicmemory-docker:/var/lib/atomicmemory/postgres \
  ghcr.io/atomicstrata/atomicmemory-core:latest

```

--------------------------------

### Initialize AtomicMemoryStore and Compile LangGraph

Source: https://docs.atomicstrata.ai/integrations/frameworks/langgraph-js/local

Demonstrates how to initialize the AtomicMemoryStore with a client and scope, and then compile a LangGraph with the store. This setup is intended for durable graph memory across runs.

```typescript
import { StateGraph } from '@langchain/langgraph';
import { AtomicMemoryStore } from '@atomicmemory/langgraph';

const store = new AtomicMemoryStore({
  client: memoryClient,
  scope: { user: userId },
});

const graph = new StateGraph(State)
  .addNode('recall', recallNode)
  .addNode('respond', respondNode)
  .compile({ store });

```

--------------------------------

### Run AtomicMemory Core Docker Container

Source: https://docs.atomicstrata.ai/quickstart

Starts the AtomicMemory core service using Docker. Mounts a volume for persistent storage and sets the OpenAI API key.

```bash
export OPENAI_API_KEY="sk-..."

docker run -d --pull always \
  --name atomicmemory-core \
  -p 127.0.0.1:3050:3050 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -v $HOME/.atomicstrata/atomicmemory-docker:/var/lib/atomicmemory/postgres \
  ghcr.io/atomicstrata/atomicmemory-core:latest
```

--------------------------------

### Initialize AtomicMemoryClient and Get Capabilities

Source: https://docs.atomicstrata.ai/sdk/guides/artifact-storage

Initializes the AtomicMemoryClient and retrieves storage capabilities. Ensure your API URL, API key, and user ID are correctly configured.

```typescript
import { AtomicMemoryClient } from '@atomicmemory/sdk';

const client = new AtomicMemoryClient({
  apiUrl: 'http://localhost:3050',
  apiKey: process.env.ATOMICMEMORY_API_KEY!,
  userId: 'demo-user',
  memory: {
    providers: {
      atomicmemory: {
        apiUrl: 'http://localhost:3050',
        apiKey: process.env.ATOMICMEMORY_API_KEY!,
      },
    },
  },
});

const capabilities = await client.storage.capabilities();
console.log(capabilities.provider, capabilities.supportsDirectUpload);
```

--------------------------------

### Search Memory via HTTP

Source: https://docs.atomicstrata.ai/platform/consuming-core

Example of how to search for memories using the HTTP API. This demonstrates sending a query and user ID to retrieve relevant information.

```APIDOC
## POST /v1/memories/search

### Description
Searches for memories based on a user ID and a query.

### Method
POST

### Endpoint
/v1/memories/search

### Request Body
- **user_id** (string) - Required - The identifier for the user whose memories to search.
- **query** (string) - Required - The search query.

### Request Example
```json
{
  "user_id": "alice",
  "query": "what stack?"
}
```

### Response
#### Success Response (200)
- **count** (integer) - The number of matching memories found.
- **injection_text** (string) - Text generated for injection, potentially based on search results.
- **memories** (array of objects) - A list of matching memories.

#### Response Example
```json
{
  "count": 5,
  "injection_text": "The user is asking about the technology stack.",
  "memories": [
    {
      "id": "memory-id-1",
      "text": "User mentioned Go on the backend.",
      "source": "my-app"
    }
  ]
}
```
```

--------------------------------

### Implement StorageAdapter for Chrome Local Storage

Source: https://docs.atomicstrata.ai/sdk/concepts/storage-adapters

Provides a minimal implementation of the StorageAdapter interface for use with chrome.storage.local. This example covers the essential methods required for a custom adapter.

```typescript
import type { StorageAdapter } from '@atomicmemory/sdk/storage';

export class ChromeStorageAdapter implements StorageAdapter {
  async initialize() {}
  async get<T>(key: string): Promise<T | null> {
    const result = await chrome.storage.local.get(key);
    return (result[key] as T) ?? null;
  }
  async set<T>(key: string, value: T): Promise<void> {
    await chrome.storage.local.set({ [key]: value });
  }
  async delete(key: string): Promise<void> {
    await chrome.storage.local.remove(key);
  }
  async clear(): Promise<void> {
    await chrome.storage.local.clear();
  }
  async has(key: string): Promise<boolean> {
    const result = await chrome.storage.local.get(key);
    return key in result;
  }
  async keys(): Promise<string[]> {
    const all = await chrome.storage.local.get(null);
    return Object.keys(all);
  }
  async batch(operations): Promise<void> {
    // delegate per op
  }
  async stats() {
    return { keyCount: (await this.keys()).length };
  }
}
```

--------------------------------

### Ingest Memory via HTTP

Source: https://docs.atomicstrata.ai/platform/consuming-core

Example of how to ingest memory into atomicmemory-core using the HTTP API. This includes setting up the request with necessary headers and body content.

```APIDOC
## POST /v1/memories/ingest

### Description
Ingests a new memory into the atomicmemory-core service.

### Method
POST

### Endpoint
/v1/memories/ingest

### Request Body
- **user_id** (string) - Required - Identifier for the user.
- **conversation** (string) - Required - The conversation or text to be stored as memory.
- **source_site** (string) - Required - The source of the memory.

### Request Example
```json
{
  "user_id": "alice",
  "conversation": "user: I ship Go on the backend.",
  "source_site": "my-app"
}
```

### Response
#### Success Response (200)
- **episode_id** (string) - The ID of the ingested episode.
- **memories_stored** (integer) - The number of memories stored.
- **stored_memory_ids** (array of strings) - IDs of the memories that were stored.
- **updated_memory_ids** (array of strings) - IDs of memories that were updated.

#### Response Example
```json
{
  "episode_id": "some-episode-id",
  "memories_stored": 1,
  "stored_memory_ids": ["memory-id-1"],
  "updated_memory_ids": []
}
```
```

--------------------------------

### Package Command JSON Output

Source: https://docs.atomicstrata.ai/cli

Example of the JSON output structure for the package command. This includes data-specific fields and metadata.

```json
{
  "status": "success",
  "command": "package",
  "duration_ms": 18,
  "profile": "default",
  "scope": { "user": "pip", "namespace": "docs" },
  "count": 2,
  "data": {
    "text": "## Relevant Memory\n...",
    "tokens": 842,
    "hits": [],
    "budgetConstrained": false
  },
  "meta": {
    "token_budget": 1200,
    "format": "tiered",
    "section": "inline",
    "budget_constrained": false
  }
}
```

--------------------------------

### Configure via Environment Variables

Source: https://docs.atomicstrata.ai/cli

Set environment variables for configuration when not using CLI flags or a config file. This is useful for CI/CD pipelines or quick setups.

```bash
export ATOMICMEMORY_PROVIDER="atomicmemory"
export ATOMICMEMORY_API_URL="http://127.0.0.1:3050"
export ATOMICMEMORY_API_KEY="local-dev-key"
export ATOMICMEMORY_TRUST_SURFACE="local"
export ATOMICMEMORY_SCOPE_USER="$USER"
export ATOMICMEMORY_SCOPE_NAMESPACE="my-project"
```

--------------------------------

### Configure local Claude Code LLM provider

Source: https://docs.atomicstrata.ai/platform/providers

Use `claude auth login` and set `LLM_PROVIDER` to `claude-code` for local development. This uses your local Claude Code installation and subscription.

```bash
claude auth login
LLM_PROVIDER=claude-code
# Optional; omit to use Claude Code's configured default.
# LLM_MODEL=sonnet
```

--------------------------------

### HTTP Request Succeeding with Agent ID

Source: https://docs.atomicstrata.ai/platform/scope

Example of a successful HTTP GET request to the list endpoint, including `agent_id` along with `workspace_id`, resulting in a 200 OK response.

```http
GET /v1/memories/list?user_id=u-123&workspace_id=ws-abc&agent_id=a-planner
HTTP/1.1 200 OK
{ "memories": [...], "count": 7 }
```

--------------------------------

### HTTP Request Failing due to Missing Agent ID

Source: https://docs.atomicstrata.ai/platform/scope

Example of an HTTP GET request to the list endpoint that will fail with a 400 Bad Request because `agent_id` is missing when `workspace_id` is provided.

```http
GET /v1/memories/list?user_id=u-123&workspace_id=ws-abc
HTTP/1.1 400 Bad Request
{ "error": "agent_id is required for workspace queries" }
```

--------------------------------

### Python Storage Client Initialization

Source: https://docs.atomicstrata.ai/sdk/guides/artifact-storage

Initializes the Python StorageClient with connection details.

```APIDOC
## Python Storage Client Initialization

### Description
Initializes the Python StorageClient.

### Method
`StorageClient(config)`

### Parameters
#### Request Body
- **config** (dict) - Required - Configuration dictionary.
  - **apiUrl** (string) - Required - The API endpoint URL.
  - **apiKey** (string) - Required - The API key for authentication.
  - **userId** (string) - Required - The user ID.
```

--------------------------------

### Initialize and use IndexedDBStorageAdapter

Source: https://docs.atomicstrata.ai/sdk/concepts/storage-adapters

Demonstrates initializing IndexedDBStorageAdapter and using it with StorageManager for basic set/get operations. Ensure the adapter is initialized before use.

```typescript
import {
  StorageManager,
  IndexedDBStorageAdapter,
} from '@atomicmemory/sdk/storage';

const adapter = new IndexedDBStorageAdapter();
await adapter.initialize({ dbName: 'my-app-storage' });

const storage = new StorageManager([adapter]);
await storage.initialize();

await storage.set('preferences', { theme: 'dark' });
const prefs = await storage.get<{ theme: string }>('preferences');
```

--------------------------------

### Install Codex Lifecycle Hooks

Source: https://docs.atomicstrata.ai/integrations/coding-agents/codex/local

Install lifecycle hooks for Codex to enable automatic prompt-time retrieval or deterministic lifecycle capture. This is used when features.codex_hooks is enabled.

```bash
atomicmemory hooks install --host codex --runtime node
```

--------------------------------

### Configure default LLM provider (OpenAI)

Source: https://docs.atomicstrata.ai/platform/providers

Set environment variables to use OpenAI for LLM. Requires `LLM_PROVIDER` and `LLM_MODEL`.

```bash
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o-mini
OPENAI_API_KEY=sk-…
```

--------------------------------

### Core Runtime Composition Root

Source: https://docs.atomicstrata.ai/platform/stores

Illustrates how the composition root in `createCoreRuntime` wires up various store implementations using a PostgreSQL pool and configuration flags.

```typescript
const memory = new MemoryRepository(pool);
const claims = new ClaimRepository(pool);
const trust = new AgentTrustRepository(pool);
const links = new LinkRepository(pool);
const entities = config.entityGraphEnabled ? new EntityRepository(pool) : null;
const lessons = config.lessonsEnabled ? new LessonRepository(pool) : null;

const stores: CoreStores = {
  memory: new PgMemoryStore(pool),
  episode: new PgEpisodeStore(pool),
  search: new PgSearchStore(pool),
  link: new PgSemanticLinkStore(pool),
  representation: new PgRepresentationStore(pool),
  claim: claims,          // ClaimRepository structurally satisfies ClaimStore
  entity: entities,       // narrowed to EntityStore at the boundary
  lesson: lessons,
  pool,
};
```

--------------------------------

### Initialize Cloud Profile with API Key from Stdin

Source: https://docs.atomicstrata.ai/cli

Initialize a cloud profile, securely passing the API key via stdin. This prevents the API key from appearing in shell history.

```bash
printf '%s\n' "$ATOMICMEMORY_API_KEY" | \
  atomicmemory init --profile cloud --api-key-stdin --save-api-key
```

--------------------------------

### Initialize Python StorageClient and Upload Pointer Artifact

Source: https://docs.atomicstrata.ai/sdk/guides/artifact-storage

Initializes the Python StorageClient and uploads a pointer artifact. Ensure the API URL, API key, and user ID are correctly provided.

```python
from atomicmemory import StorageClient

with StorageClient({
    "apiUrl": "http://localhost:3050",
    "apiKey": "server-api-key",
    "userId": "demo-user",
}) as client:
    artifact = client.put({
        "mode": "pointer",
        "uri": "ipfs://bafy...",
        "contentType": "application/pdf",
    })
    print(artifact.artifact_id)

    meta = client.get({"artifact_id": artifact.artifact_id})
    print(meta.status)
```

--------------------------------

### Get Memory Audit Trail

Source: https://docs.atomicstrata.ai/api-reference/http/get-memory-audit-trail

Fetches the audit trail for a specific memory.

```APIDOC
## GET /v1/memories/{id}/audit

### Description
Per-memory version history.

### Method
GET

### Endpoint
/v1/memories/{id}/audit

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the memory.
#### Query Parameters
- **user_id** (string) - Required - The identifier of the user.

### Responses
#### Success Response (200)
- **Audit trail** (object) - Contains the audit trail information.

#### Error Responses
- **400** - Input validation error
- **500** - Internal server error
```

--------------------------------

### Get Managed Artifact Content

Source: https://docs.atomicstrata.ai/sdk/guides/artifact-storage

Retrieves the raw bytes content of a managed artifact.

```APIDOC
## Get Managed Artifact Content

### Description
Retrieves the raw bytes content of a managed artifact.

### Method
`client.storage.getContent(options)`

### Parameters
#### Request Body
- **options** (object) - Required - Options for retrieving the content.
  - **artifactId** (string) - Required - The ID of the artifact whose content to retrieve.

### Response
#### Success Response
- **body** (ReadableStream or bytes) - The raw bytes content of the artifact.
```

--------------------------------

### Initialize and Use MemoryClient

Source: https://docs.atomicstrata.ai/sdk/overview

Instantiate MemoryClient with provider configuration, initialize it, and then use it for ingesting messages and performing searches. Ensure the provider URL and API key are correctly set.

```typescript
import { MemoryClient } from '@atomicmemory/sdk';

const memory = new MemoryClient({
  providers: {
    atomicmemory: {
      apiUrl: 'http://localhost:3050',
      apiKey: 'local-dev-key',
    },
  },
});
await memory.initialize();

await memory.ingest({
  mode: 'messages',
  messages: [{ role: 'user', content: 'I prefer aisle seats.' }],
  scope: { user: 'u1' },
});

const results = await memory.search({
  query: 'seat preference',
  scope: { user: 'u1' },
});
```

--------------------------------

### Get User Memory Statistics

Source: https://docs.atomicstrata.ai/api-reference/http/get-stats

Retrieves aggregate memory statistics for a specified user.

```APIDOC
## GET /v1/memories/stats

### Description
Aggregate memory statistics for a user.

### Method
GET

### Endpoint
/v1/memories/stats

### Parameters
#### Query Parameters
- **user_id** (string) - Required - The ID of the user for whom to retrieve statistics.

### Response
#### Success Response (200)
- **payload** (object) - Stats payload.

#### Error Response (400)
- **error** (object) - Input validation error.

#### Error Response (500)
- **error** (object) - Internal server error.
```

--------------------------------

### Subsystem liveness + current runtime config snapshot.

Source: https://docs.atomicstrata.ai/llms.txt

Checks the liveness of subsystems and retrieves a snapshot of the current runtime configuration.

```APIDOC
## Subsystem liveness + current runtime config snapshot.

### Description
Checks the operational status (liveness) of various subsystems and provides a snapshot of the current runtime configuration.

### Method
GET

### Endpoint
/get-memory-health
```

--------------------------------

### Get Agent Trust

Source: https://docs.atomicstrata.ai/api-reference/http/get-agent-trust

Retrieves the trust level for a given user and agent ID.

```APIDOC
## GET /v1/agents/trust

### Description
Look up the trust level for a (user, agent) pair.

### Method
GET

### Endpoint
/v1/agents/trust

### Parameters
#### Query Parameters
- **agent_id** (string) - Required - Required. agent_id.
- **user_id** (string) - Required - Required. user_id.

### Responses
#### Success Response (200)
- **agent_id** (string) - The ID of the agent.
- **trust_level** (number) - The trust level between the user and the agent.

#### Error Responses
- **400** - Input validation error
- **500** - Internal server error
```

--------------------------------

### Get Pointer Artifact Metadata

Source: https://docs.atomicstrata.ai/sdk/guides/artifact-storage

Retrieves metadata for a pointer artifact using its artifact ID.

```APIDOC
## Get Pointer Artifact Metadata

### Description
Retrieves metadata for a pointer artifact.

### Method
`client.storage.get(options)`

### Parameters
#### Request Body
- **options** (object) - Required - Options for retrieving the artifact.
  - **artifactId** (string) - Required - The ID of the artifact to retrieve.

### Response
#### Success Response
- **status** (string) - The status of the artifact.
- **uri** (string) - The URI associated with the pointer artifact.
```

--------------------------------

### Get deferred-mutation reconciliation status.

Source: https://docs.atomicstrata.ai/llms.txt

Retrieves the current status of deferred mutation reconciliation processes.

```APIDOC
## Get deferred-mutation reconciliation status.

### Description
Returns the status of operations that are pending reconciliation for deferred mutations.

### Method
GET

### Endpoint
/get-reconcile-status
```

--------------------------------

### Configuration and Skill Management Commands

Source: https://docs.atomicstrata.ai/cli

Commands for managing CLI configuration profiles and retrieving skills.

```bash
atomicmemory config show
atomicmemory config profile list
atomicmemory config profile use cloud
atomicmemory config profile show local
atomicmemory skill get core
```

--------------------------------

### Get Lesson Stats

Source: https://docs.atomicstrata.ai/api-reference/http/get-lesson-stats

Retrieves the count of active lessons for a user, categorized by lesson type.

```APIDOC
## GET /v1/memories/lessons/stats

### Description
Return the count of currently active lessons for a user, broken down by lesson type — a lightweight per-user health signal. A lesson is a recorded failure pattern (blocked injection, low-trust write, high-confidence contradiction, or user report) that future retrievals filter against. Use this endpoint to surface a count badge or alert on spikes (e.g. sustained growth in `injection_blocked`) without exposing the raw pattern text.

### Method
GET

### Endpoint
/v1/memories/lessons/stats

### Parameters
#### Query Parameters
- **user_id** (string) - Required - The ID of the user for whom to retrieve lesson statistics.

### Responses
#### Success Response (200)
- **Stats** (object) - Contains the lesson statistics.

#### Response Example
```json
{
  "injection_blocked": 5,
  "low_trust_write": 2,
  "high_confidence_contradiction": 1,
  "user_report": 0
}
```

#### Error Response (400)
Input validation error.

#### Error Response (500)
Internal server error.
```

--------------------------------

### Select and Verify Hermes Memory Provider

Source: https://docs.atomicstrata.ai/integrations/coding-agents/hermes/local

Use Hermes CLI commands to set up and check the status of the AtomicMemory provider. This confirms the integration is active.

```bash
hermes memory setup
hermes memory status
```

--------------------------------

### Get Audit Summary

Source: https://docs.atomicstrata.ai/api-reference/http/get-audit-summary

Retrieves aggregated mutation statistics for a user's memory store.

```APIDOC
## GET /v1/memories/audit/summary

### Description
Aggregate mutation statistics for a user's memory store.

### Method
GET

### Endpoint
/v1/memories/audit/summary

### Parameters
#### Query Parameters
- **user_id** (string) - Required - The ID of the user whose memory store audit summary is to be retrieved.

### Responses
#### Success Response (200)
- **Mutation summary** (object) - Contains the aggregated mutation statistics.

#### Error Responses
- **400** - Input validation error
- **500** - Internal server error
```

--------------------------------

### Stop and Start AtomicMemory Core Container

Source: https://docs.atomicstrata.ai/quickstart

Commands to stop and then restart the AtomicMemory core Docker container.

```bash
docker stop atomicmemory-core
docker start atomicmemory-core
```

--------------------------------

### Python Get Artifact Metadata

Source: https://docs.atomicstrata.ai/sdk/guides/artifact-storage

Retrieves metadata for an artifact using its artifact ID with the Python SDK.

```APIDOC
## Python Get Artifact Metadata

### Description
Retrieves metadata for an artifact using its artifact ID with the Python SDK.

### Method
`client.get(options)`

### Parameters
#### Request Body
- **options** (dict) - Required - Options for retrieving the artifact.
  - **artifact_id** (string) - Required - The ID of the artifact to retrieve.

### Response
#### Success Response
- **status** (string) - The status of the artifact.
```

--------------------------------

### Run Live Filecoin Document Upload Tests

Source: https://docs.atomicstrata.ai/platform/artifact-storage

Execute live integration tests for encrypted Filecoin document uploads. This command runs the document upload pipeline against the calibration Filecoin network, verifies ciphertext storage, and decodes retrieved bytes using the AES-GCM codec. Ensure you have the necessary environment variables set in `.env.test` and `.env.foc.local`.

```bash
FILECOIN_LIVE_DOCUMENT_UPLOAD_TESTS=1 \
  dotenv -e .env.test -e .env.foc.local -- npx vitest run \
  "src/services/__tests__/document-upload-filecoin-live.test.ts" \
  --reporter=verbose --testTimeout=900000
```

--------------------------------

### GET /:id

Source: https://docs.atomicstrata.ai/platform/scope

Retrieves a specific memory by its ID. Similar to `/list`, workspace queries require an `agent_id`.

```APIDOC
## GET /:id

### Description
Retrieves a specific memory by its ID. If scoped to a workspace, `agent_id` is required.

### Method
GET

### Endpoint
/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the memory to retrieve.

#### Query Parameters
- **user_id** (string) - Required - The ID of the user.
- **workspace_id** (string) - Optional - The ID of the workspace.
- **agent_id** (string) - Required if `workspace_id` is present - The ID of the agent within the workspace.

### Response
#### Success Response (200)
- **memory** (object) - The memory object.

### Error Handling
- **400 Bad Request**: If `workspace_id` is provided without `agent_id`.
```

--------------------------------

### Run AtomicMemory Core with Hybrid Search Enabled

Source: https://docs.atomicstrata.ai/integrations/frameworks/vercel-ai-sdk/local

Restart the `atomicmemory-core` Docker container with the `RETRIEVAL_PROFILE` environment variable set to 'quality' to enable hybrid search. This ensures better performance for factual recall.

```bash
docker rm -f atomicmemory-core

docker run -d --pull always \
  --name atomicmemory-core \
  -p 127.0.0.1:3050:3050 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -e RETRIEVAL_PROFILE=quality \
  -v $HOME/.atomicstrata/atomicmemory-docker:/var/lib/atomicmemory/postgres \
  ghcr.io/atomicstrata/atomicmemory-core:latest
```

--------------------------------

### Get Memory Provider Capabilities

Source: https://docs.atomicstrata.ai/sdk/concepts/capabilities

Retrieve the Capabilities object from a memory provider to inspect its supported features.

```typescript
const caps = memory.capabilities();
// {
//   ingestModes: ['text', 'messages', 'memory'],
//   requiredScope: { default: ['user'], ingest: ['user', 'namespace'] },
//   extensions: { package: true, temporal: true, versioning: true, health: true, ... },
//   customExtensions: { ... },
// }
```

--------------------------------

### Configure Local AtomicMemory Backend

Source: https://docs.atomicstrata.ai/integrations/coding-agents/hermes/local

Set environment variables to point Hermes to a local AtomicMemory instance. Ensure the AtomicMemory core is running before configuring.

```bash
export ATOMICMEMORY_API_URL="http://127.0.0.1:3050"
export ATOMICMEMORY_API_KEY="local-dev-key"
```

--------------------------------

### Memory Management Commands

Source: https://docs.atomicstrata.ai/cli

Commands for adding, ingesting, searching, listing, getting, deleting, and importing memories.

```bash
atomicmemory add "The project uses pnpm workspaces."
atomicmemory ingest --mode verbatim "Decision recap for handoff"
atomicmemory ingest --mode messages --file ./conversation.json
atomicmemory search "workspace package conventions" --limit 5
atomicmemory package "recent implementation context" --token-budget 1200
atomicmemory list --limit 20
atomicmemory get <memory-id>
atomicmemory delete <memory-id>
atomicmemory import ./memories.json
```

--------------------------------

### Get Recent Audit

Source: https://docs.atomicstrata.ai/api-reference/http/get-recent-audit

Fetches recent audit mutations for a given user ID, with an optional limit.

```APIDOC
## GET /v1/memories/audit/recent

### Description
Recent mutations for a user, limit-bounded.

### Method
GET

### Endpoint
/v1/memories/audit/recent

### Parameters
#### Query Parameters
- **user_id** (string) - Required - The ID of the user for whom to retrieve audit mutations.
- **limit** (string) - Optional - The maximum number of audit mutations to return.

### Responses
#### Success Response (200)
- **Recent mutations.**

#### Error Responses
- **400** - Input validation error
- **500** - Internal server error
```

--------------------------------

### Initialize and Use AtomicMemoryClient with Storage

Source: https://docs.atomicstrata.ai/sdk/overview

Instantiate AtomicMemoryClient to leverage both memory and artifact storage. Configure the API URL, API key, and user ID. Use the storage.put method to upload artifacts.

```typescript
import { AtomicMemoryClient } from '@atomicmemory/sdk';

const client = new AtomicMemoryClient({
  apiUrl: 'http://localhost:3050',
  apiKey: process.env.ATOMICMEMORY_API_KEY!,
  userId: 'u1',
  memory: {
    providers: {
      atomicmemory: {
        apiUrl: 'http://localhost:3050',
        apiKey: process.env.ATOMICMEMORY_API_KEY!,
      },
    },
  },
});

const artifact = await client.storage.put({
  mode: 'pointer',
  uri: 'ipfs://bafy...',
  contentType: 'application/pdf',
});
```