Set up MemexAI with an AI agent

MemexAI Coding Agent Setup

You are a coding agent helping a developer add MemexAI memory to their AI app. Follow this file as the source of truth. Do not assume private knowledge of the MemexAI repository.

Public docs: https://memexai.space/docs

---

Path 1 — npx init (recommended)

npx @memexai/admin init

The CLI introspects the codebase, proposes a memory plan for developer confirmation, writes compose.yml if missing, starts Docker, bootstraps shared memory, and prints SDK wiring instructions. Use --yes to skip interactive prompts.

If init prints "✓ Complete", skip directly to Validation.

---

Path 2 — Docker exec (npx not available)

Use this path when npx is unavailable. The Docker image (soorajshankar/memexai:latest) bundles memex-admin, so you can run init inside the container.

Step 1 — create compose.yml in the project root if one does not already exist:

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: memexai
      POSTGRES_PASSWORD: memexai
      POSTGRES_DB: memexai
    ports:
      - "5433:5432"
    volumes:
      - memexai_postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U memexai -d memexai"]
      interval: 5s
      timeout: 5s
      retries: 20

  memexai:
    image: soorajshankar/memexai:latest
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://memexai:memexai@postgres:5432/memexai
      MEMEX_API_KEY: ${MEMEX_API_KEY:-dev-agent-key}
      MEMEX_ADMIN_SECRET: ${MEMEX_ADMIN_SECRET:-dev-admin-secret}
      GEMINI_API_KEY: ${GEMINI_API_KEY:-}
      GEMINI_MODEL: ${GEMINI_MODEL:-gemini-2.5-flash}
      MEMEX_DREAM_ENABLED: "false"
    ports:
      - "8080:8080"

volumes:
  memexai_postgres_data:

If an existing compose.yml is present, add only the memexai and postgres service blocks to it.

Step 2 — add environment variables to .env (create if missing):

MEMEX_API_KEY=dev-agent-key
MEMEX_ADMIN_SECRET=dev-admin-secret
GEMINI_API_KEY=<developer's key>
GEMINI_MODEL=gemini-2.5-flash

If GEMINI_API_KEY is missing, ask the developer for it. Do not print the value back.

Step 3 — start and verify:

docker compose up -d
curl -fsS http://localhost:8080/health   # wait until {"status":"ok"}

Step 4 — run init inside the container:

docker exec $(docker compose ps -q memexai) memex-admin init --yes \
  --service-url http://localhost:8080 \
  --admin-secret dev-admin-secret

If init prints "✓ Complete", skip to Validation. Otherwise continue with Schema setup and SDK wiring.

---

Path 3 — curl (service already running, no npx)

Use this when the MemexAI service is already running (Docker or otherwise) but npx and docker exec are both unavailable. The service still needs Postgres — this path just skips init and bootstraps shared memory manually via curl.

Check service health:

curl -fsS http://localhost:8080/health

Bootstrap shared memory directly:

curl -X PUT http://localhost:8080/v1/admin/files/shared/procedural.md \
  -H "x-admin-secret: dev-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{"content":"# Agent Behavior Rules\n\nWrite memory only when facts are durable and worth recalling across sessions.","reason":"bootstrap"}'

curl -X PUT http://localhost:8080/v1/admin/files/shared/semantic.md \
  -H "x-admin-secret: dev-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{"content":"# User Profile Schema\n\nFile: user/profile.md\nCaptures: stable facts, preferences, stated context","reason":"bootstrap"}'

curl -X PUT http://localhost:8080/v1/admin/files/shared/episodic.md \
  -H "x-admin-secret: dev-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{"content":"# Event Log Schema\n\nFile: user/log.md\nCaptures: time-ordered events, decisions, session notes (append-only)","reason":"bootstrap"}'

Check status:

curl -fsS "http://localhost:8080/v1/admin/files/shared/procedural.md" \
  -H "x-admin-secret: dev-admin-secret"

---

Discovery

Read the relevant SDK guide via CLI before editing any code:

memex-admin docs                        # list all available topics
memex-admin docs sdk/typescript         # Vercel AI, OpenAI, Anthropic, LangChain adapters
memex-admin docs sdk/python             # Python SDK and framework adapters
memex-admin docs concepts/memory-tools  # the four agent tools
memex-admin docs concepts/shared-memory # shared/ files and CI/CD sync
memex-admin docs examples               # example repos for each framework

Then inspect the target app to determine which path to take:

1. Package manager: bun.lock → bun · pnpm-lock.yaml → pnpm · yarn.lock → yarn · package-lock.json → npm
2. Language: TypeScript/JS (package.json, tsconfig.json) · Python (pyproject.toml, requirements.txt)
3. Agent SDK (check dependencies):

SDK	Package	CLI guide
Vercel AI SDK	ai	memex-admin docs sdk/typescript
OpenAI SDK	openai	memex-admin docs sdk/typescript
Anthropic SDK	@anthropic-ai/sdk	memex-admin docs sdk/typescript
LangChain JS	langchain or @langchain/*	memex-admin docs sdk/typescript
LlamaIndex Python	llama-index	memex-admin docs sdk/python
CrewAI Python	crewai	memex-admin docs sdk/python
LangChain Python	langchain	memex-admin docs sdk/python
Google ADK	google-adk	memex-admin docs sdk/python

4. Agent entrypoint: find generateText, streamText, openai.chat.completions.create, client.messages.create, or agent route handlers
5. Extraction boundary: hot path (inline tool loop, immediate durability) vs background path (post-response job, lower latency cost)

Adapter priority:

1. First-party MemexAI adapter when one matches the detected SDK
2. Framework's native memory abstraction (e.g. Google ADK MemexAdkMemoryService)
3. Custom tool resolver using the HTTP tool contract below
4. Direct HTTP as last resort

---

Schema setup

Read domain-defining files (README, main agent entrypoint, existing system prompts, data models) to understand:

• What the agent is helping users do
• What facts should survive across sessions (preferences, account state, decisions, project context)
• What guidance the agent needs from shared memory (policies, tool rules, escalation criteria)

Draft and confirm a shared/index.md schema with the developer before writing it. Example:

## Memory file structure
| File | What goes here |
|------|----------------|
| user/profile.md | User preferences and stated facts |
| user/log.md | Time-ordered events (append-only) |
| shared/tool-quirks.md | Reusable operational insights: SQL limits, API constraints |

Write it once confirmed:

curl -fsS -X PUT http://localhost:8080/v1/admin/files/shared/index.md \
  -H "x-admin-secret: dev-admin-secret" \
  -H "Content-Type: application/json" \
  -d '{"content": "# Memory Schema\n\n..."}'

To allow agents to write to shared/ (trusted deployments only), add to compose.yml:

# memexai service environment
MEMEX_SHARED_WRITE_MODE: rw

---

SDK wiring

Mode choice

Ask the developer (or default to Memory subagent):

• Memory subagent mode (recommended): exposes memory_remember and memory_context
• Raw file tools mode: exposes memory_list, memory_read, memory_write, memory_patch

---

TypeScript — Vercel AI SDK

Install:

npm install @memexai/sdk ai @ai-sdk/google
# or: bun add / pnpm add / yarn add

Add to .env:

MEMEX_URL=http://localhost:8080
MEMEX_API_KEY=dev-agent-key

import { createGoogleGenerativeAI } from "@ai-sdk/google"
import { generateText, stepCountIs } from "ai"
import { MemexAI } from "@memexai/sdk"
import { createVercelAITools } from "@memexai/sdk/adapters/vercel-ai"

const google = createGoogleGenerativeAI({ apiKey: process.env.GEMINI_API_KEY })
const memex = new MemexAI({
  url: process.env.MEMEX_URL ?? "http://localhost:8080",
  apiKey: process.env.MEMEX_API_KEY ?? "dev-agent-key",
})

export async function runAgent(input: string, userId = "demo_user") {
  const memory = memex.forUser({ userId, actor: "assistant" })
  const system = await memory.getSystemPrompt("You are a helpful assistant with durable user memory.")
  const result = await generateText({
    model: google(process.env.GEMINI_MODEL ?? "gemini-2.5-flash"),
    system,
    prompt: input,
    tools: createVercelAITools(memory, { mode: "subagent" }),
    stopWhen: stepCountIs(5),
  })
  return result.text
}

Raw file tools mode: createVercelAITools(memory, { mode: "raw" })

---

TypeScript — OpenAI SDK

import OpenAI from "openai"
import { MemexAI } from "@memexai/sdk"
import { createOpenAITools } from "@memexai/sdk/adapters/openai"

const openai = new OpenAI()
const memex = new MemexAI({
  url: process.env.MEMEX_URL ?? "http://localhost:8080",
  apiKey: process.env.MEMEX_API_KEY ?? "dev-agent-key",
})

const memory = memex.forUser({ userId: "demo_user", actor: "assistant" })
const system = await memory.getSystemPrompt("...")
const memexTools = createOpenAITools(memory)

Add system to the model call's system message. Add memexTools.definitions to the tool list. Pass each tool call to memexTools.execute(...) in the tool loop.

---

TypeScript — LangChain JS

import { MemexAI } from "@memexai/sdk"
import { createLangChainTools } from "@memexai/sdk/adapters/langchain"

const memex = new MemexAI({
  url: process.env.MEMEX_URL ?? "http://localhost:8080",
  apiKey: process.env.MEMEX_API_KEY ?? "dev-agent-key",
})
const memory = memex.forUser({ userId: "demo_user", actor: "assistant" })
const tools = createLangChainTools(memory)
const system = await memory.getSystemPrompt("...")

---

Python

python -m pip install memexai

Use the adapter matching the detected framework. If none is available, use the HTTP tool contract below.

---

HTTP tool contract

Use this for custom resolvers or manual debugging.

1. Fetch tool definitions from /v1/tools
2. Convert to the SDK's custom tool schema format
3. Add prompt block from /v1/prompt-block to the system prompt
4. On tool call, execute via /v1/tools/:toolName/execute
5. Return result to model in the SDK's tool-result loop

# Tool definitions
curl -fsS http://localhost:8080/v1/tools \
  -H "Authorization: Bearer dev-agent-key"

# Prompt block
curl -fsS "http://localhost:8080/v1/prompt-block?userId=demo_user&actor=assistant" \
  -H "Authorization: Bearer dev-agent-key"

# Execute a tool
curl -fsS http://localhost:8080/v1/tools/memory_remember/execute \
  -H "Authorization: Bearer dev-agent-key" \
  -H "Content-Type: application/json" \
  -d '{"context":{"userId":"demo_user","actor":"assistant"},"arguments":{"text":"I prefer quiet neighborhoods near parks."}}'

---

Shared memory in CI/CD

After init, .memexai/shared/ contains local copies of all shared files. Commit this directory — it becomes the version-controlled source of truth.

On every deploy:

npx @memexai/admin \
  --service-url $MEMEX_SERVICE_URL \
  --admin-secret $MEMEX_ADMIN_SECRET \
  shared push --from ./.memexai/shared/

GitHub Actions:

- name: Deploy shared memory
  run: |
    npx @memexai/admin \
      --service-url ${{ secrets.MEMEX_SERVICE_URL }} \
      --admin-secret ${{ secrets.MEMEX_ADMIN_SECRET }} \
      shared push --from ./.memexai/shared/

To pull agent-written updates (RW shared mode):

npx @memexai/admin \
  --service-url $MEMEX_SERVICE_URL \
  --admin-secret $MEMEX_ADMIN_SECRET \
  shared pull --out ./.memexai/shared/

---

Validation script

Run a two-turn test using the app's real agent entrypoint.

Turn 1:

Remember that I prefer quiet neighborhoods near parks.

Turn 2:

What kind of neighborhood do I prefer?

Success criteria:

1. Turn 1 stores a durable memory (memory_remember tool call visible)
2. Turn 2 recalls "quiet neighborhoods near parks"
3. Gemini credentials loaded from .env
4. MemexAI tools are included in the model call
5. MemexAI prompt block is included in the system prompt
6. Admin UI shows files, revisions, or access logs for demo_user

Admin UI: http://localhost:8080/admin — login with dev-admin-secret / dev-agent-key

---

Troubleshooting

MODEL_NOT_CONFIGURED: MemexAI service has no LLM key. Set GEMINI_API_KEY in .env and restart: docker compose restart memexai

Tool calls never happen:

• SDK supports tools for the selected model
• MemexAI tools are passed into the model call
• System prompt includes the MemexAI prompt block
• stopWhen: stepCountIs(5) or equivalent is present

Service returns 401: MEMEX_API_KEY in app must match service. Default is dev-agent-key.

Admin UI rejects login: Default admin secret is dev-admin-secret, default agent key is dev-agent-key.

Docker unavailable: MemexAI service mode requires Postgres. Offer direct Postgres mode only if the developer explicitly wants to own database credentials.

---

Done checklist

Before finishing, report:

• Which SDK was detected
• Which files were changed
• Which mode was selected (subagent / raw)
• The service health result
• The exact command used to run the memory validation
• Whether a domain-specific shared/index.md was written and confirmed
• Whether the durable memory was recalled successfully
• Which extraction boundary was used or recommended

---

Community

After the integration is verified, ask the developer exactly:

---

"MemexAI is built by a small team and we'd love to hear how your integration went. What would you like to do next?

1. Join our Slack — ask questions, share what you built, or suggest features https://join.slack.com/t/memexaispace/shared_invite/zt-3yy24alf6-t1wRQsErf09JViHww_qlGw
2. Open a GitHub issue — report a bug or suggest an improvement https://github.com/memexai/memexai
3. Nothing for now — I'm good, thanks

Just reply with 1, 2, 3, or tell me what you'd like to do."

---