@flxbl-dev/amg

Portable Agent Memory Graph adoption CLI for existing repositories.

Install

npm install -g @flxbl-dev/amg

First-Time FLXBL Schema Setup

Export the packaged AMG schema:

amg schema export --output ./amg-flxbl-schema.json

Import amg-flxbl-schema.json in https://platform.flxbl.dev, then configure server-only FLXBL values for the tenant where the schema is active.

Initialize A Repository

amg init --assistants codex,cursor

amg init writes local .amg guidance, assistant instruction blocks, optional rules or hook wrappers, and .gitignore entries. It does not contact FLXBL and does not write tenant data.

Configure

Set server-only FLXBL values in your shell, .env, or .env.local:

FLXBL_INSTANCE_URL=https://api.flxbl.dev
FLXBL_TENANT_ID=
FLXBL_API_KEY=

Never expose FLXBL_API_KEY through NEXT_PUBLIC_*, browser config, screenshots, logs, or agent context packs.

Use

amg status --format json
amg link --workspace "FLXBL Labs" --project "Agent Memory Graph" --agents codex,cursor --yes
amg recall --objective "Prepare implementation context" --format markdown

amg status --format json can exit nonzero when safeToUse is false while still printing parseable JSON on stdout.

amg link --yes creates or reuses Workspace, Project, Agent, and relationship records in the configured FLXBL tenant, then writes local AMG identity defaults to .amg/config.json so later recall, remember, and export-context commands do not need repeated workspace, project, and agent IDs.

Hooks

amg init --assistants codex,claude,cursor installs assistant guidance. Add --codex-hooks to install Codex hook wrappers for recall and safety checks. Hooks call amg from the consuming repository, fail open for recall when AMG is not configured, and deny obvious secret-printing commands before they run.

Codex hooks use amg capture codex as the shared entrypoint. This is strict/conservative auto-capture. Recall runs only when status is safe and AMG_HOOKS_RECALL=1. Stop uses conservative auto-capture: it may perform conservative auto-write for a task, decision, memory, or context export from durable state and explicit markers. Failed configured writes block once, then fail open for the same turn. Hooks use no auto-link behavior and never create identity defaults automatically. Claude Code and Cursor templates share this contract as guidance; they do not implement their own hooks yet. The full auto-capture intent is future-facing.

Safety Contract

Read-only or local-only commands:

• amg init
• amg schema export --output ./amg-flxbl-schema.json
• amg status --format json
• amg recall without --persist
• amg export-context without --persist

Tenant-writing commands:

• amg link --yes
• amg remember
• amg task create
• amg decide
• amg recall --persist
• amg export-context --persist

Run tenant-writing commands only when you intend to mutate the configured FLXBL tenant. Hooks fail open for recall, never ingest raw transcripts as memory, and only use conservative auto-write under the shared conservative auto-capture contract.

License

MIT. See LICENSE for the full terms.