### Install Dependencies and Start Dev Server

Source: https://github.com/coasys/ad4m/blob/dev/ui/README.md

Run these commands in separate terminals to start the frontend development server.

```shell
pnpm install
pnpm start
```

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

### Run AD4M Setup

Source: https://github.com/coasys/ad4m/blob/dev/plugins/ad4m/README.md

Initiate the interactive setup for the AD4M plugin. This command automates the process of finding or downloading the AD4M executor, starting it, generating an agent identity, and providing a configuration snippet.

```bash
openclaw ad4m-setup
```

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

### Example Usage of QuerySubscriptionProxy

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/classes/QuerySubscriptionProxy.html

Demonstrates how to subscribe to a Prolog query, set up a callback for results, and dispose of the subscription. The `subscribeInfer` method waits for initialization, simplifying the setup.

```javascript
const subscription = await perspective.subscribeInfer("my_query(X)");
// At this point the subscription is already initialized since subscribeInfer waits
 
// Set up callback for future updates
const removeCallback = subscription.onResult(result => {
    console.log("New result:", result);
});
 
// Later: clean up subscription and notify backend
subscription.dispose();
```

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

### Create and Configure a SHACLFlow

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/classes/SHACLFlow.html

Instantiate a SHACLFlow and define its properties, states, start action, and transitions. This example demonstrates how to set up a 'TODO' flow with 'ready', 'doing', and 'done' states and their associated transitions. Use this to model custom workflows for AD4M expressions.

```javascript
const todoFlow = new SHACLFlow('todo://TODO', 'todo://');
 
 // Any expression can become a TODO
 todoFlow.flowable = 'any';
 
 // Define states
 todoFlow.addState({
   name: 'ready',
   value: 0,
   stateCheck: { predicate: 'todo://state', target: 'todo://ready' }
 });
 todoFlow.addState({
   name: 'doing', 
   value: 0.5,
   stateCheck: { predicate: 'todo://state', target: 'todo://doing' }
 });
 todoFlow.addState({
   name: 'done',
   value: 1,
   stateCheck: { predicate: 'todo://state', target: 'todo://done' }
 });
 
 // Define start action
 todoFlow.startAction = [{
   action: 'addLink',
   source: 'this',
   predicate: 'todo://state',
   target: 'todo://ready'
 }];
 
 // Define transitions
 todoFlow.addTransition({
   actionName: 'Start',
   fromState: 'ready',
   toState: 'doing',
   actions: [
     { action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://doing' },
     { action: 'removeLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }
   ]
 });
 
 // Store in perspective
 await perspective.addFlow('TODO', todoFlow);
```

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

### Install Project Dependencies

Source: https://github.com/coasys/ad4m/blob/dev/README.md

Installs all project dependencies using pnpm. This command should be run after cloning the repository.

```bash
pnpm install
```

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

### AD4M Plugin Setup

Source: https://github.com/coasys/ad4m/blob/dev/plugins/ad4m/skills/ad4m/SKILL.md

Commands for installing and setting up the AD4M plugin for OpenClaw. Includes profile creation and image setting.

```bash
1. Install plugin                 → openclaw plugins install ./ad4m
2. Run setup                      → openclaw ad4m-setup
3. Paste config into openclaw.json (printed by setup)
4. Restart OpenClaw
5. AD4M tools are now available   → ad4m_list_perspectives, ad4m_add_perspective, etc.
6. Create profile                 → ad4m_set_agent_profile(username: "...")
7. Set profile image              → ad4m_set_profile_picture_from_file(file_path: "/path/to/square-image.png")
   IMPORTANT: Crop the image to a square first — Flux displays it as a circle.
```

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

### IncludeMap Usage Examples

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/interfaces/IncludeMap.html

Examples demonstrating how to use the IncludeMap interface to specify eager-loading of relations.

```APIDOC
## IncludeMap

Describes which relations to eager-load when querying.

Each value is either:

*   `true` — hydrate the relation one level deep
*   A `RelationSubQuery` — scoped sub-query (filter / sort / paginate / nested include)

**`Example`**

    // One level deep
    { comments: true }
     
    // Sub-query: only the 5 most-recent comments
    { comments: { order: { createdAt: 'DESC' }, limit: 5 } }
     
    // Nested eager-load
    { comments: { include: { author: true } } }

Indexable[](#indexable)
-----------------------

▪ [relation: `string`]: `boolean` | [`RelationSubQuery`](/jsdoc/modules#relationsubquery)
```

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

### Capability Specification Examples

Source: https://github.com/coasys/ad4m/blob/dev/docs/auth.html

Examples of how to specify required capabilities, including requesting all access, read-only access to a specific perspective, or specific operations on a domain.

```javascript
{ with: { domain: "*", pointers: ["*"] }, can: ["*"] }
```

```javascript
{ with: { domain: "perspective-uuid", pointers: ["*"] }, can: ["read"] }
```

```javascript
{ with: { domain: "friends", pointers: ["*"] }, can: ["read", "add", "remove"] }
```

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

### Install and Run ad4m-executor

Source: https://github.com/coasys/ad4m/blob/dev/core/README.md

Install the ad4m-cli tool and run the ad4m-executor. Ensure the executor is running before connecting with Ad4mClient.

```sh
cargo install ad4m
ad4m-executor run
```

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

### Install macOS Dependencies

Source: https://github.com/coasys/ad4m/blob/dev/cli/README.md

Installs protobuf and cmake using Homebrew for macOS users.

```bash
brew install protobuf cmake
```

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

### Install AD4M Connect

Source: https://github.com/coasys/ad4m/blob/dev/connect/README.md

Install the AD4M Connect library using npm.

```bash
npm install -s @coasys/ad4m-connect
```

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

### Install and List AD4M Languages

Source: https://github.com/coasys/ad4m/blob/dev/docs/languages.html

Demonstrates how to install a new language using its address and how to retrieve a list of all currently installed languages within the AD4M environment.

```javascript
// Install a language from its address
await ad4m.languages.install("Qm...");
 
// List all installed languages
const languages = await ad4m.languages.all();
```

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

### Example Perspective Links

Source: https://github.com/coasys/ad4m/blob/dev/docs/spanning-layer.html

Demonstrates how to represent data using triples in an RDF-like graph structure within a perspective. This example shows a post with a title and author.

```turtle
<did:key:z6Mk...>  <ad4m://posted>      <ipfs://Qm789>
<ipfs://Qm789>     <ad4m://has_title>   "Hello World"
<ipfs://Qm789>     <ad4m://has_author>  <did:key:z6Mk...>
```

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

### Install AD4M Connect Library

Source: https://github.com/coasys/ad4m/blob/dev/docs/installation.html

Install the higher-level AD4M Connect library for streamlined UI integration, including authentication handling.

```bash
npm install @coasys/ad4m-connect
```

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

### Install Linux Dependencies

Source: https://github.com/coasys/ad4m/blob/dev/README.md

Installs a comprehensive set of development libraries and tools for Linux (Ubuntu/Debian), including GTK, WebKit, Protobuf, CMake, and Rust ALSA bindings.

```bash
sudo apt-get update
sudo apt-get install -y \
  libgtk-3-dev webkit2gtk-4.0 libappindicator3-dev \
  librsvg2-dev patchelf protobuf-compiler cmake \
  fuse libfuse2 mesa-utils mesa-vulkan-drivers \
  libsoup-3.0-dev javascriptcoregtk-4.1-dev \
  webkit2gtk-4.1-dev librust-alsa-sys-dev
```

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

### Local Single-User AD4M Executor Deployment

Source: https://github.com/coasys/ad4m/blob/dev/plugins/ad4m/skills/ad4m/references/setup.md

Example configuration for running the AD4M executor in a simple single-user, local setup. No TLS is required as the agent and executor are on the same machine.

```bash
ad4m-executor run --app-data-path ~/.ad4m --port 12000 \
  --admin-credential mysecret --enable-mcp true
# MCP at http://localhost:3001/mcp
# API at http://localhost:12000
```

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

### Install Windows Dependencies

Source: https://github.com/coasys/ad4m/blob/dev/cli/README.md

Installs required tools for Windows using Chocolatey.

```bash
choco install strawberryperl protoc cmake curl cygwin gnuwin32-m4 msys2 make mingw
```

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

### Install Linux Dependencies

Source: https://github.com/coasys/ad4m/blob/dev/cli/README.md

Installs necessary development libraries for AD4M on Ubuntu/Debian systems.

```bash
sudo apt-get update
sudo apt-get install -y libgtk-3-dev webkit2gtk-4.0 libappindicator3-dev librsvg2-dev patchelf protobuf-compiler cmake fuse libfuse2 mesa-utils mesa-vulkan-drivers libsoup-3.0-dev javascriptcoregtk-4.1-dev webkit2gtk-4.1-dev librust-alsa-sys-dev
```

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

### Install AD4M Core Client Library

Source: https://github.com/coasys/ad4m/blob/dev/docs/installation.html

Install the core AD4M client library for JavaScript UI projects using npm.

```bash
npm install @coasys/ad4m
```

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

### Install UTILS Module for Browser

Source: https://github.com/coasys/ad4m/blob/dev/docs-src/host-contract.md

Installs the UTILS module, which provides a canonical content-address hash function. The output is expected in AD4M-canonical format (SHA-256 -> CIDv1 -> base58btc, prefixed with 'Qm').

```javascript
globalThis.UTILS = {
    hash: (data) => canonicalAd4mHash(data),  // SHA-256 -> CIDv1 -> "Qm..."
};
```

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

### Verify Go Installation

Source: https://github.com/coasys/ad4m/blob/dev/cli/README.md

Checks if the installed Go version meets the AD4M requirement of 1.22.0 or later.

```bash
go version  # Should show 1.22.0 or later
```

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

### Install AD4M CLI Tools

Source: https://github.com/coasys/ad4m/blob/dev/cli/README.md

Installs the AD4M command-line interface tools using Cargo.

```bash
cargo install ad4m
```

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

### Install Node.js and pnpm

Source: https://github.com/coasys/ad4m/blob/dev/README.md

Installs the Node.js package manager (npm) globally and recommends Node.js version 24+. pnpm is used for package management.

```bash
npm install -g pnpm
```

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

### Capability Request Examples

Source: https://github.com/coasys/ad4m/blob/dev/connect/README.md

Examples of capability requests, ranging from full access (for development) to read-only access on a specific perspective or specific operations on a domain.

```javascript
// Full access (development only)
{ with: { domain: "*", pointers: ["*"] }, can: ["*"] }
```

```javascript
// Read-only access to a perspective
{ with: { domain: "perspective-uuid", pointers: ["*"] }, can: ["read"] }
```

```javascript
// Specific operations on a domain
{ with: { domain: "friends", pointers: ["*"] }, can: ["read", "add", "remove"] }
```

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

### AI Agent Session Example with MCP Tools

Source: https://context7.com/coasys/ad4m/llms.txt

This TypeScript example demonstrates an AI agent interacting with AD4M via MCP tools. It covers creating a shared workspace, writing structured data, and querying the knowledge graph.

```typescript
// Tools exposed to AI agents via MCP:
// neighbourhood_join(url)          — join a shared space
// neighbourhood_create(name)       — create a new shared space
// perspective_add_link(...)        — write a semantic triple
// perspective_query_links(...)     — read triples matching a pattern
// perspective_infer(query)         — Prolog reasoning over the graph
// expression_create(content, lang) — publish a signed expression
// expression_get(url)              — retrieve a signed expression
// ai_prompt(taskId, prompt)        — run a local AI task
// agent_me()                       — get own DID and profile
// agent_get(did)                   — look up another agent's profile

// Example AI agent session (Claude using MCP tools):
// 1. Create a shared workspace
const nh = await mcp.call('neighbourhood_create', { name: 'Project Alpha' });
// 2. Write structured data
await mcp.call('perspective_add_link', {
  uuid: nh.uuid, source: 'self', predicate: 'project://status', target: 'Literal://active'
});
// 3. Query knowledge graph
const links = await mcp.call('perspective_query_links', {
  uuid: nh.uuid, predicate: 'project://status'
});
```

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

### AIPromptExamples Class

Source: https://github.com/coasys/ad4m/blob/dev/docs/index.html

Documentation for the AIPromptExamples class, providing example prompts for AI interactions.

```APIDOC
## AIPromptExamples

### Description
Provides examples of prompts for AI interactions.

### Class
AIPromptExamples
```

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

### Eager Loading with `findOne` and `get`

Source: https://github.com/coasys/ad4m/blob/dev/docs/developer-guides/model-classes.html

Demonstrates eager loading for single model instances using `findOne` and the `get` method on an instance. The `include` option can be passed directly to these methods.

```javascript
const recipe = await Recipe.findOne(perspective, {
      where: { name: "Cake" },
      include: { comments: true }
    });
     
    // And on instance get()
    const recipe = new Recipe(perspective, existingId);
    await recipe.get({ include: { comments: true } });
    // Shorthand:
    await recipe.get({ comments: true });
```

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

### ModelQueryBuilder Example

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/classes/ModelQueryBuilder.html

Demonstrates how to use the ModelQueryBuilder to define query conditions.

```APIDOC
## ModelQueryBuilder

### Description
The query builder for chaining operations on data models.

### Method
(Implicitly called via chaining)

### Parameters
#### Query Parameters (Example Usage)
- **category** (string) - Optional - Filters by category.
- **rating** (object) - Optional - Filters by rating, e.g., `{ gt: 4 }`.
- **tags** (array) - Optional - Filters by tags, e.g., `['vegan', 'quick']`.
- **published** (boolean) - Optional - Filters by published status.

### Request Example
```javascript
.where({
  category: "Dessert",
  rating: { gt: 4 },
  tags: ["vegan", "quick"],
  published: true
})
```

### Response
(The response structure depends on the chained methods and the underlying data model.)
```

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

### AIPromptExamplesInput Class

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/interfaces/GetAllAdapter.html

Input structure for AI prompt examples.

```APIDOC
## Class: AIPromptExamplesInput

### Description
Input structure for AI prompt examples.

### Methods
(Specific methods are not detailed in the provided source.)
```

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

### Get Available Flows

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/classes/PerspectiveProxy.html

Returns all Social DNA flows that can be started from the given expression address.

```javascript
await perspective.availableFlows(exprAddr);
```

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

### AIPromptExamples Constructor

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/classes/AIPromptExamples.html

Initializes a new instance of the AIPromptExamples class with input and output strings.

```APIDOC
## new AIPromptExamples(input, output)

### Description
Constructs a new AIPromptExamples instance.

### Parameters
#### Parameters
- **input** (string) - The input string for the prompt example.
- **output** (string) - The output string for the prompt example.

### Defined in
[ai/Tasks.ts:27](https://github.com/coasys/ad4m/blob/58a48e968/core/src/ai/Tasks.ts#L27)
```

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

### Define Custom Language Expression Types

Source: https://github.com/coasys/ad4m/blob/dev/docs/index.html

Example interface for a custom language, defining how to create and get expressions. The 'create' function handles data transformation and returns an address, while 'get' fetches and transforms data for the UI.

```typescript
    interface CustomLanguage {
      hash: "QmCustom321";
      name: "my-social-app";
      expressionTypes: {
        create: (content: { text: string }) => {
            /* handle any transformation required here, save the data, and return its address */
            return "QmCustom321://post789";
        },
        get: (address: string) => {
            /* fetch the data here, handle any transformation required, and return it to the UI */
            return { text: string };
        };
      };
    }
```

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

### Build Project from Source

Source: https://github.com/coasys/ad4m/blob/dev/core/README.md

Standard npm commands to install dependencies and build the project from source.

```bash
npm i && npm run build
```

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

### HostingUserInfo Constructor

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/classes/HostingUserInfo.html

Initializes a new instance of the HostingUserInfo class.

```APIDOC
## new HostingUserInfo(email, remainingCredits, hotWalletAddress?, freeAccess?)

### Description
Constructs a new HostingUserInfo object.

### Parameters
#### Parameters
- **email** (string) - The email address of the user.
- **remainingCredits** (string) - The number of remaining credits.
- **hotWalletAddress** (string, optional) - The user's hot wallet address.
- **freeAccess** (boolean, optional) - Indicates if the user has free access. Defaults to false.
```

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

### AI Agent Workflow Example

Source: https://github.com/coasys/ad4m/blob/dev/docs/developer-guides/mcp.html

Demonstrates a typical AI agent workflow: listing perspectives, discovering models, creating a task, adding tags, and querying open tasks.

```shell
# 1. List perspectives
→ perspective_list()
← [{ uuid: "ab23...", name: "My Space", neighbourhood: null }]

# 2. Discover available models
→ get_models(perspective_id: "ab23...")
← [{ name: "Task", properties: ["title", "status", "assignee"],
      collections: ["tags"] }]

# 3. Create a task
→ task_create(perspective_id: "ab23...", title: "Review MCP docs",
              status: "open", assignee: "did:key:z6Mk...")
← { uri: "ad4m://task_1234", success: true }

# 4. Add tags
→ task_add_tags(perspective_id: "ab23...", uri: "ad4m://task_1234",
                value: "documentation")
← { success: true }

# 5. Query all open tasks
→ query_subjects(perspective_id: "ab23...", class_name: "Task",
                 filter: { status: "open" })
← [{ uri: "ad4m://task_1234", title: "Review MCP docs", status: "open" }]
```

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

### AIPromptExamplesInput Constructor

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/classes/AIPromptExamplesInput.html

Initializes a new instance of the AIPromptExamplesInput class with provided input and output strings.

```APIDOC
## new AIPromptExamplesInput(input, output)

### Description
Constructs a new AIPromptExamplesInput instance.

### Parameters
#### Parameters
- **input** (string) - The input string for the AI prompt.
- **output** (string) - The output string for the AI prompt.

### Defined in
[ai/Tasks.ts:12](https://github.com/coasys/ad4m/blob/58a48e968/core/src/ai/Tasks.ts#L12)
```

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

### Publish and Get Languages in AD4M

Source: https://github.com/coasys/ad4m/blob/dev/docs-src/pages/index.mdx

Publish a new custom language to the network and retrieve a list of all installed languages. Ensure the language code is correctly bundled and referenced.

```javascript
const languageMeta = {
  name: "my-social-app",
  description: "A custom social app language"
};
const published = await ad4mClient.languages.publish("./build/bundle.js", languageMeta);
console.log(published.address); // QmCustom321

// Get all installed languages
const languages = await ad4mClient.languages.all();
console.log(languages); // Includes the newly published language
```

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

### Interact with Social DNA Flows Programmatically

Source: https://github.com/coasys/ad4m/blob/dev/docs-src/pages/social-dna.mdx

Provides functions to manage and query flows within a perspective. Use these to get available flows, check flow states, start flows, and execute actions.

```typescript
// Get all flows defined in a perspective
const flows = await perspective.sdnaFlows();
// Returns: ["TODO"]

// Check what flows are available for an expression
const availableFlows = await perspective.availableFlows("expression://123");

// Start a flow on an expression
await perspective.startFlow("TODO", "expression://123");

// Get expressions in a specific flow state
const readyTodos = await perspective.expressionsInFlowState("TODO", 0);

// Get current state of an expression in a flow
const state = await perspective.flowState("TODO", "expression://123");
// Returns: 0, 0.5, or 1

// Get available actions for current state
const actions = await perspective.flowActions("TODO", "expression://123");
// Returns: ["Start"] if in ready state

// Execute an action
await perspective.runFlowAction("TODO", "expression://123", "Start");
// Transitions from ready (0) to doing (0.5)
```

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

### SHACLFlow Constructor and Basic Usage

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/classes/SHACLFlow.html

Demonstrates how to instantiate a SHACLFlow, define its flowable condition, add states, set a start action, and add transitions. It also shows how to store the flow in a perspective.

```APIDOC
## SHACLFlow

### Description

SHACL Flow - represents a state machine for AD4M expressions. Flows define which expressions can enter the flow (flowable condition), what states exist and how to detect them (via link patterns), and how to transition between states (via actions).

### Example

```javascript
const todoFlow = new SHACLFlow('todo://TODO', 'todo://');
 
// Any expression can become a TODO
todoFlow.flowable = 'any';
 
// Define states
todoFlow.addState({
  name: 'ready',
  value: 0,
  stateCheck: { predicate: 'todo://state', target: 'todo://ready' }
});
todoFlow.addState({
  name: 'doing',
  value: 0.5,
  stateCheck: { predicate: 'todo://state', target: 'todo://doing' }
});
todoFlow.addState({
  name: 'done',
  value: 1,
  stateCheck: { predicate: 'todo://state', target: 'todo://done' }
});
 
// Define start action
todoFlow.startAction = [{
  action: 'addLink',
  source: 'this',
  predicate: 'todo://state',
  target: 'todo://ready'
}];
 
// Define transitions
todoFlow.addTransition({
  actionName: 'Start',
  fromState: 'ready',
  toState: 'doing',
  actions: [
    { action: 'addLink', source: 'this', predicate: 'todo://state', target: 'todo://doing' },
    { action: 'removeLink', source: 'this', predicate: 'todo://state', target: 'todo://ready' }
  ]
});
 
// Store in perspective
await perspective.addFlow('TODO', todoFlow);
```

### Methods

#### `constructor(name: string, namespace: string)`

Initializes a new SHACLFlow instance.

- **name** (string) - The name of the flow.
- **namespace** (string) - The namespace for the flow.

#### `addState(state: { name: string, value: number, stateCheck: object })`

Adds a new state to the flow.

- **state** (object) - An object containing the state definition:
  - **name** (string) - The name of the state.
  - **value** (number) - A numerical value associated with the state.
  - **stateCheck** (object) - An object defining how to check for this state.

#### `addTransition(transition: { actionName: string, fromState: string, toState: string, actions: Array<object> })`

Adds a transition between two states in the flow.

- **transition** (object) - An object defining the transition:
  - **actionName** (string) - The name of the action that triggers this transition.
  - **fromState** (string) - The name of the state to transition from.
  - **toState** (string) - The name of the state to transition to.
  - **actions** (Array<object>) - An array of actions to perform during the transition.

#### `toJSON()`

Serializes the SHACLFlow object to a JSON representation.

#### `toLinks()`

Converts the SHACLFlow object into a list of links.

#### `fromJSON(json: object)`

Creates a SHACLFlow object from a JSON representation.

#### `fromLinks(links: Array<object>)`

Creates a SHACLFlow object from a list of links.
```

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

### Define Minimal Expression Language in TypeScript

Source: https://github.com/coasys/ad4m/blob/dev/docs-src/pages/languages.mdx

Use `defineLanguage` to create a pure transform for a grouped spec, emitting flat named exports for the runtime. This example shows a minimal 'note-store' language with create and get expression capabilities.

```typescript
import {
    defineLanguage,
    agentCreateSignedExpression,
    hash,
    storageGet,
    storagePut,
} from "@coasys/ad4m-ldk";

export default defineLanguage({
    name: "note-store",
    version: "1.0.0",

    async init() {
        // Language-specific setup. Runtime imports (e.g. languageSettings)
        // are callable here.
    },

    expression: {
        async create(content) {
            const expr = agentCreateSignedExpression(content);
            const s = JSON.stringify(expr);
            const address = hash(s);          // canonical AD4M content hash
            storagePut(address, s);
            return address;
        },

        async get(address) {
            const raw = storageGet(address);
            return raw ? JSON.parse(raw) : null;
        },
    },
});
```

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

### Initialize Ad4mClient

Source: https://github.com/coasys/ad4m/blob/dev/core/README.md

Install the Ad4mClient library and initialize a client instance to connect to the running ad4m-executor. The client connects to the default executor address.

```js
npm install --save @coasys/ad4m
```

```js
import { Ad4mClient } from '@coasys/ad4m'

const ad4mClient = new Ad4mClient("http://localhost:12000")
```

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

### Install AD4M CLI

Source: https://github.com/coasys/ad4m/blob/dev/README.md

Installs the AD4M command-line interface tool. It can be installed from crates.io or built locally from the cli directory.

```bash
cargo install ad4m
```

```bash
cd cli && cargo build --release
```

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

### Start AD4M ExpressionUI Local Server

Source: https://github.com/coasys/ad4m/blob/dev/test-runner/README.md

Launch a local server with ExpressionUI for testing expression language UIs. This command requires specifying the language bundle and meta information.

```cli
ad4m-test --ui --bundle languages/sdp.js --meta '{\"name\":\"shortform-expression\",\"description\":\"Shortform expression for flux application\",\"sourceCodeLink\":\"https://github.com/juntofoundation/ad4m-languages\",\"possibleTemplateParams\":[\"uid\",\"name\"]}'
```

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

### Install Rust Toolchain

Source: https://github.com/coasys/ad4m/blob/dev/README.md

Installs Rust version 1.92, sets it as the default, and adds the WASM target. Ensure Rust 1.92 or later is installed.

```bash
rustup install 1.92
rustup default 1.92
rustup target add wasm32-unknown-unknown
```

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

### Android Manifest Setup

Source: https://github.com/coasys/ad4m/blob/dev/connect/README.md

Add these lines to your `android/app/src/main/AndroidManifest.xml` file to enable hardware acceleration and declare necessary permissions and SDK overrides for mobile integration.

```diff
<?xml version="1.0" encoding="utf-8"?>
<manifest
  xmlns:android="http://schemas.android.com/apk/res/android"
+  xmlns:tools="http://schemas.android.com/tools"
  package="com.example">

  <application
+    android:hardwareAccelerated="true"
  >
  </application>

+  <uses-permission android:name="android.permission.CAMERA" />

+  <uses-sdk tools:overrideLibrary="com.google.zxing.client.android" />
</manifest>
```

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

### Install AD4M Plugin

Source: https://github.com/coasys/ad4m/blob/dev/plugins/ad4m/README.md

Install the AD4M plugin for OpenClaw using the OpenClaw CLI. For local development, use the -l flag to install from a local path.

```bash
openclaw plugins install @coasys/openclaw-ad4m
```

```bash
openclaw plugins install -l plugins/ad4m
```

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

### Simple ad4m-connect Client Setup

Source: https://context7.com/coasys/ad4m/llms.txt

Initializes the AD4M client using `getAd4mClient()`, which blocks until authentication is complete. Requires application details and capabilities.

```typescript
import { getAd4mClient, getAd4mConnect } from '@coasys/ad4m-connect';

// Simple – blocks until authentication is complete
const client = await getAd4mClient({
  appName: 'Notes App',
  appDesc: 'Personal note-taking',
  appDomain: 'com.example.notes',
  capabilities: [
    {
      with: { domain: 'agent', pointers: ['*'] },
      can: ['READ'],
    },
    {
      with: { domain: 'perspective', pointers: ['*'] },
      can: ['READ', 'CREATE', 'UPDATE', 'DELETE'],
    },
  ],
  port: 12000,
});
```

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

### Creating Model Instances: Instantiate and Save

Source: https://github.com/coasys/ad4m/blob/dev/docs/developer-guides/model-classes.html

Demonstrates the first method for creating model instances: instantiating the class, setting properties, and then explicitly saving the instance to the perspective.

```typescript
// Option 1: Instantiate and save
    const recipe = new Recipe(perspective);
    recipe.name = "Chocolate Cake";
    await recipe.save();
```

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

### Creating Model Instances

Source: https://github.com/coasys/ad4m/blob/dev/docs-src/pages/developer-guides/model-classes.mdx

Demonstrates different ways to create new model instances, including instantiation and saving, static creation, and creating with specific IDs or parent relationships.

```APIDOC
## Creating Model Instances

### Option 1: Instantiate and save
```typescript
const recipe = new Recipe(perspective);
recipe.name = "Chocolate Cake";
await recipe.save();
```

### Option 2: Static create (one-step)
```typescript
const recipe = await Recipe.create(perspective, { name: "Chocolate Cake" });
```

### Create with a specific ID
```typescript
const recipe = new Recipe(perspective, "recipe://chocolate-cake");
await recipe.save();
```

### Create with a parent relationship
```typescript
const recipe = await Recipe.create(perspective, { name: "Cake" }, {
  parent: { model: Cookbook, id: cookbook.id }
});
```
```

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

### Create UI Bundle

Source: https://github.com/coasys/ad4m/blob/dev/README.md

Creates a UI bundle for the AD4M Launcher using pnpm. The resulting bundle will be located in `target/release/bundle`.

```bash
pnpm run package-ad4m
```

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

### Joining a Neighbourhood Example

Source: https://github.com/coasys/ad4m/blob/dev/docs/developer-guides/mcp.html

Shows how an AI agent can join an existing neighborhood, discover available models within it, and send a message.

```shell
# Join an existing neighbourhood
→ join_neighbourhood(url: "neighbourhood://Qm...")
← { perspective_id: "cd45...", state: "SYNCED" }

# Discover what models (SHACL subject classes) exist in this community
→ get_models(perspective_id: "cd45...")
← [{ name: "Message", properties: ["body", "author", "timestamp"],
      collections: ["reactions"] }]

# Send a message (uses the auto-generated message_create tool)
→ message_create(perspective_id: "cd45...", body: "Hello from an AI agent! 🖖")
← { uri: "ad4m://msg_5678", success: true }
```

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

### Install @coasys/ad4m-ldk

Source: https://github.com/coasys/ad4m/blob/dev/ad4m-ldk/js/README.md

Install the AD4M Language Development Kit using npm or pnpm.

```sh
npm install @coasys/ad4m-ldk
# or
pnpm add @coasys/ad4m-ldk
```

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

### Start AD4M Executor

Source: https://github.com/coasys/ad4m/blob/dev/docs/developer-guides/cli.html

Start the AD4M executor service. Ensure an instance is running before interacting with the client.

```bash
ad4m-executor run
```

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

### Initialize and Run AD4M Executor

Source: https://github.com/coasys/ad4m/blob/dev/cli/README.md

Initializes the AD4M executor configuration and then starts the core executor process.

```bash
ad4m-executor init
```

```bash
ad4m-executor run
```

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

### PerspectiveProxy: Create, Add, and Query Links

Source: https://github.com/coasys/ad4m/blob/dev/docs-src/pages/perspectives.mdx

Demonstrates how to use the PerspectiveProxy class to create a new Perspective, add a Link, and query existing Links within that Perspective.

```typescript
// Create a new Perspective
const perspective = await ad4m.perspective.add("My Knowledge Graph");

// Add a Link
await perspective.add({
    source: "QmSocial123://post789",
    predicate: "sioc://likes",
    target: "did:key:z6Mk..."
});

// Query Links
const links = await perspective.get({
    source: "QmSocial123://post789"
});
```

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

### Install Rust Toolchain for AD4M

Source: https://github.com/coasys/ad4m/blob/dev/cli/README.md

Installs the required Rust toolchain version and the WASM target for building Holochain DNAs.

```bash
rustup install 1.84.0
rustup default 1.84.0
```

```bash
rustup target add wasm32-unknown-unknown
```

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

### Real-time Prolog Query Subscription

Source: https://github.com/coasys/ad4m/blob/dev/docs/perspectives.html

Set up real-time query subscriptions with Prolog for dynamic data updates. Remember to call `dispose()` on the subscription when it's no longer needed to prevent memory leaks.

```javascript
const subscription = await perspective.subscribeInfer(
  'triple(Post, "sioc://status", "active"), triple(Post, "sioc://author", Author)'
);

subscription.onResult(results => {
    console.log("Active posts and their authors:", results);
});

subscription.dispose();
```

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

### OpenClaw Plugin Configuration Example

Source: https://github.com/coasys/ad4m/blob/dev/plugins/ad4m/README.md

Example of how to integrate the AD4M plugin configuration into your openclaw.json file. Paste the generated snippet into the 'config' field.

```json5
{
  plugins: {
    entries: {
      "ad4m": {
        enabled: true,
        config: {
          // paste the snippet here
          "mode": "managed",
          "ad4mBinaryPath": "/path/to/ad4m-executor",
          "agentPassphrase": "your-generated-passphrase"
        }
      }
    }
  }
}
```

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

### Configure AD4M Executor with Basic Parameters

Source: https://github.com/coasys/ad4m/blob/dev/docs/developer-guides/cli.html

Customize the executor's behavior using various configuration parameters. This example shows basic settings like GraphQL port, data path, and DApp server.

```bash
ad4m-executor run \
  --gql-port 12000 \
  --admin-credential secret \
  --app-data-path ./data \
  --run-dapp-server true
```

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

### Install Certbot (Ubuntu/Debian)

Source: https://github.com/coasys/ad4m/blob/dev/docs/multi-user.html

Install the certbot tool on Ubuntu/Debian systems to obtain TLS certificates. This is a prerequisite for securing your AD4M node's connection.

```bash
sudo apt install certbot
```

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

### Create and Manage Links with PerspectiveProxy

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/classes/PerspectiveProxy.html

Demonstrates creating a new perspective, adding links (subject-predicate-object triples), and querying existing links.

```javascript
const perspective = await ad4m.perspective.add("My Space");
    await perspective.add({
      source: "did:key:alice",
      predicate: "knows",
      target: "did:key:bob"
    });
     
    // Query links
    const friends = await perspective.get({
      source: "did:key:alice",
      predicate: "knows"
    });
     
```

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

### Build Project

Source: https://github.com/coasys/ad4m/blob/dev/rust-executor/MIGRATION_REMOVAL_GUIDE.md

Compile the project to verify that all migration-related code has been removed.

```bash
cargo build --lib
```

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

### Build AD4M Launcher for Specific OS

Source: https://github.com/coasys/ad4m/blob/dev/ui/README.md

Install dependencies and then run the build command corresponding to your operating system (macOS, Windows, or Linux).

```shell
pnpm install
pnpm run build-macos/windows/linux (choose your correct OS)
```

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

### Install AGENT Module for Browser

Source: https://github.com/coasys/ad4m/blob/dev/docs-src/host-contract.md

Installs the AGENT module, which interfaces with a remote executor via HTTP API. It includes a method to fetch the agent's DID.

```javascript
globalThis.AGENT = {
    did: () => fetch("/api/agent/did").then(r => r.text()),
    // ... or use cached DID + Web Crypto for local signing
};
```

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

### Deno Executor File I/O

Source: https://github.com/coasys/ad4m/blob/dev/docs-src/host-contract.md

Example of using Deno's built-in file I/O functions, which are sandboxed by Deno's filesystem permission allow-list.

```javascript
Deno.readTextFileSync(path)
Deno.writeTextFileSync(path, content)
```

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

### Publish and Install AD4M Language

Source: https://github.com/coasys/ad4m/blob/dev/docs/index.html

Publish a new custom language to the network and retrieve its address. Later, fetch all installed languages, which will include the newly published one.

```javascript
    // Publish a new language
    const languageMeta = {
      name: "my-social-app",
      description: "A custom social app language"
    };
    const published = await ad4mClient.languages.publish("./build/bundle.js", languageMeta);
    console.log(published.address); // QmCustom321
     
    // Get all installed languages
    const languages = await ad4mClient.languages.all();
    console.log(languages); // Includes the newly published language
```

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

### Run Integration Tests

Source: https://github.com/coasys/ad4m/blob/dev/rust-executor/LANGUAGE_RUNTIME_PHASE1.md

Instructions to navigate to the JavaScript tests directory and execute them.

```bash
cd tests/js
pnpm test
```

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

### Neighbourhood Expression Example

Source: https://github.com/coasys/ad4m/blob/dev/docs/neighbourhoods.html

An example of a Neighbourhood Expression published in the Neighbourhood Bootstrap Language. It contains the address of the LinkLanguage for synchronization and optional metadata like name and description.

```json
{
        data: {
            linkLanguage: "QmLinkLang123...",  // Address of the sync language
            meta: {  // Optional metadata
                name: "My Team Space",
                description: "Collaboration space for our team"
            }
        }
    }
```

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

### Working with Perspectives using PerspectiveProxy

Source: https://github.com/coasys/ad4m/blob/dev/docs/perspectives.html

Demonstrates how to create a new Perspective, add a Link to it, and query for existing Links using the PerspectiveProxy class.

```javascript
// Create a new Perspective
const perspective = await ad4m.perspective.add("My Knowledge Graph");
 
// Add a Link
await perspective.add({
    source: "QmSocial123://post789",
    predicate: "sioc://likes",
    target: "did:key:z6Mk..."
});
 
// Query Links
const links = await perspective.get({
    source: "QmSocial123://post789"
});
```

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

### Live Query Subscription (Explicit Prolog)

Source: https://github.com/coasys/ad4m/blob/dev/docs/developer-guides/surreal-queries.html

Subscribe to real-time updates for 'Recipe' records using Prolog instead of SurrealDB. This allows for using Prolog's query engine for subscriptions.

```typescript
// Subscribe using Prolog
    await Recipe.query(perspective)
      .where({ rating: { gt: 4 } })
      .useSurrealDB(false)
      .subscribe((recipes) => {
        console.log("Updated recipes (Prolog):", recipes);
      });
```

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

### Send a Message

Source: https://github.com/coasys/ad4m/blob/dev/docs-src/pages/developer-guides/mcp.mdx

This example demonstrates how to send a message using the auto-generated `message_create` tool. The message is validated, signed, and synced to all members of the shared space.

```APIDOC
## Send a Message (uses the auto-generated message_create tool)
→ message_create(perspective_id: "cd45...", body: "Hello from an AI agent! 🖖")
← { uri: "ad4m://msg_5678", success: true }
```

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

### Install LANGUAGE_CONTROLLER Module for Browser

Source: https://github.com/coasys/ad4m/blob/dev/docs-src/host-contract.md

Installs the LANGUAGE_CONTROLLER module, providing core methods for language management. It supports optional file I/O via localStorage and emits various signals.

```javascript
globalThis.LANGUAGE_CONTROLLER = {
    languageStorageDirectory: () => "indexeddb://lang-storage/" + langAddr,
    languageAddress: () => langAddr,
    languageSettings: () => settingsJson,

    // OPTIONAL: File I/O extension. Omit these entirely if this runtime
    // doesn't support raw file I/O — the KV will work in-memory-only and
    // languages importing readStorageFile will throw a clear error on call.
    readStorageFile: (path) => {
        const data = localStorage.getItem("ad4m-storage:" + path);
        if (data === null) throw new Error("NotFound: " + path);
        return data;
    },
    writeStorageFile: (path, content) => {
        localStorage.setItem("ad4m-storage:" + path, content);
    },

    // Events via postMessage or EventTarget
    perspectiveDiffReceived: (diff, addr) => { /* dispatch */ },
    syncStateChanged: (state, addr) => { /* dispatch */ },
    telepresenceSignalReceived: (sig, addr, did) => { /* dispatch */ },
    ad4mSignalEmitted: (sig, addr) => { /* dispatch */ },
    registerHolochainSignalHandler: (cellId, addr) => { /* no-op or WebSocket */ },
};
```

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

### Example AD4M Expression Object

Source: https://github.com/coasys/ad4m/blob/dev/docs/expressions.html

An example of a concrete AD4M Expression object, illustrating the fields and their expected data types. Note that 'valid' and 'invalid' flags are added by AD4M during retrieval.

```json
{
  "author": "did:key:zQ3shv5VUAbtY5P1jGsPzy7L27FTxeDv2hnhVp9QT3ALNCnQ2",
  "timestamp": "2023-06-21T14:47:48.935Z",
  "data": "Hello World!",
  "language": {
    "address": "literal"
  },
  "proof": {
    "valid": true,     // Added by AD4M during retrieval
    "invalid": false,  // Added by AD4M during retrieval
    "signature": "...", // The stored signature
    "key": "..." // Key path in the author's DID Document used for signing
  }
}
```

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

### Get First Matching Instance

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/classes/ModelQueryBuilder.html

Retrieves the first record that matches the query criteria. If no records match, it returns `null`. This is achieved internally by setting `limit: 1` and calling `get()`.

```typescript
const recipe = await Recipe.query(perspective)
      .where({ name: "Pasta" })
      .first();
```

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

### Capability Constructor

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/classes/Capability.html

Initializes a new Capability instance. It takes a Resource and an array of strings representing the capabilities.

```APIDOC
## new Capability(withF, can)

### Description
Initializes a new Capability instance.

### Parameters
#### Parameters
- **withF** (Resource) - The resource associated with the capability.
- **can** (string[]) - An array of strings representing the specific capabilities.

### Defined in
[agent/Agent.ts:165](https://github.com/coasys/ad4m/blob/58a48e968/core/src/agent/Agent.ts#L165)
```

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

### AIPromptExamplesInput Class

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/classes/AIPromptExamplesInput.html

Provides details on the AIPromptExamplesInput class, its constructor, and its properties 'input' and 'output'.

```APIDOC
## Class: AIPromptExamplesInput

### Description

This class is part of the @coasys/ad4m project and is related to AI prompt examples.

### Constructors

#### constructor(input, output)

*   **input** (any) - Description for input parameter.
*   **output** (any) - Description for output parameter.

### Properties

#### input

*   Type: any
*   Description: Represents the input for the AI prompt example.

#### output

*   Type: any
*   Description: Represents the output for the AI prompt example.
```

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

### Example AD4M Expression URLs

Source: https://github.com/coasys/ad4m/blob/dev/docs-src/pages/languages.mdx

These examples illustrate how different protocols are represented within the AD4M universal addressing scheme, including Git commits, IPFS CIDs, wiki pages, and DID documents.

```text
QmGitLang…://abcdef1234…
```

```text
QmIPFSLang…://QmZXY…
```

```text
QmWikiLang…://article-42
```

```text
did:key:z6Mk…
```

```text
<your-hash>://<your-address>
```

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

### DNS A Record Example

Source: https://github.com/coasys/ad4m/blob/dev/docs/multi-user.html

Example of how to configure a DNS A record to point a domain name to your server's public IP address. This is crucial for making your AD4M node discoverable by remote users.

```dns
ad4m.example.com.  A  203.0.113.42
```

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

### Publish, Install, and Use AD4M Languages

Source: https://github.com/coasys/ad4m/blob/dev/docs-src/pages/languages.mdx

Demonstrates the lifecycle of an AD4M Language: publishing a new language bundle, installing it on a node, and then using it to create and retrieve expressions. Ensure the path to the bundle is correct.

```javascript
// Publish: returns the language-hash that becomes your Language's address
const meta = await ad4m.languages.publish(
    "/path/to/bundle.js",
    { name: "note-store", description: "A simple note store" },
);

// Install on another node (or the same one later)
await ad4m.languages.install(meta.address);

// Use: all Expression operations go through the universal address format
const exprAddr = await ad4m.expression.create("Hello World", meta.address);
const expr     = await ad4m.expression.get(`${meta.address}://${exprAddr}`);
```

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

### iOS Info.plist Setup

Source: https://github.com/coasys/ad4m/blob/dev/connect/README.md

Add the `NSCameraUsageDescription` key and a descriptive string to your `Info.plist` file to explain why camera access is needed for scanning barcodes.

```diff
<dict>
+  <key>NSCameraUsageDescription</key>
+  <string>To be able to scan barcodes</string>
</dict>
```

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

### getRelationsMetadata

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/modules.html

Gets metadata for relations.

```APIDOC
## getRelationsMetadata

### Description
Gets metadata for relations.

### Parameters
This function does not have explicitly documented parameters in the source.
```

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

### getPropertyOption

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/modules.html

Gets a property option.

```APIDOC
## getPropertyOption

### Description
Gets a property option.

### Parameters
This function does not have explicitly documented parameters in the source.
```

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

### Joining a Neighbourhood

Source: https://github.com/coasys/ad4m/blob/dev/docs-src/pages/developer-guides/mcp.mdx

This example shows how an AI agent can join a shared neighbourhood using its URL and then discover the available models within that community's perspective.

```shell
# Join an existing neighbourhood
→ join_neighbourhood(url: "neighbourhood://Qm...")
← { perspective_id: "cd45...", state: "SYNCED" }

# Discover what models (SHACL subject classes) exist in this community
→ get_models(perspective_id: "cd45...")
← [{ name: "Message", properties: ["body", "author", "timestamp"],
      collections: ["reactions"] }]
```

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

### RuntimeInfo Constructor

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/classes/RuntimeInfo.html

Initializes a new instance of the RuntimeInfo class.

```APIDOC
## new RuntimeInfo()

### Description
Initializes a new instance of the RuntimeInfo class.

### Method
constructor

### Parameters
None
```

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

### getPropertiesMetadata

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/modules.html

Gets metadata for properties.

```APIDOC
## getPropertiesMetadata

### Description
Gets metadata for properties.

### Parameters
This function does not have explicitly documented parameters in the source.
```

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

### getApps

Source: https://github.com/coasys/ad4m/blob/dev/docs/jsdoc/classes/AgentClient.html

Retrieves a list of installed applications.

```APIDOC
## getApps()

### Description
Retrieves a list of all applications currently installed on the agent.
```