axgram

The CLI for Axgram — a multi-tenant AI memory system. The axgram binary mines local codebases, imports conversation history from your AI tools, sets up Axgram in your AI coding tools (axgram init), and runs the auto-save hooks. The axgram-hook binary is a separate, slimmer entrypoint that those hooks invoke.

Install

npm install -g axgram

Permissions (EACCES)? If npm install -g axgram fails with EACCES, your npm global prefix is system-owned. Either install to a user-owned prefix — npm config set prefix ~/.npm-global and add ~/.npm-global/bin to your PATH — or re-run with sudo. The user-prefix route avoids sudo, but ~/.npm-global/bin must be on the PATH Claude Code launches with, or its hooks won't find axgram-hook. A sudo install lands in /usr/bin, which is on essentially every PATH, so hooks resolve reliably.

Next step: installing only puts the CLI on your PATH — it does not configure anything. Run axgram init to wire hooks (and optionally the MCP server) for your AI tools.

Quick start

# 1. Authenticate (opens a browser for the magic-link flow)
axgram login

# 2. List the projects you have access to
axgram projects ls

# 3. Bind the current git repo to a project (or create a new one)
axgram projects link <project-id>
# or:
axgram projects create "My Project" && axgram projects link <new-id>

# 4. Mine your local codebase
axgram mine ./src

# 5. Import conversation history
axgram import chatgpt   ~/Downloads/conversations.json
axgram import claude    ~/Downloads/claude-export.json
axgram import gemini    ~/Downloads/gemini-takeout.json
axgram import obsidian  ~/Documents/MyVault
axgram import markdown  ~/Documents/notes  --wing notes

Project resolution

Most commands need to know which Axgram project they're operating in. Resolution chain (highest precedence first):

1. --project <id> flag
2. AXGRAM_PROJECT_ID environment variable
3. Repo binding for the current git origin (axgram projects link)
4. Global default (axgram projects use <id>)

If none of the above resolve, commands exit 1 with a clear hint. The axgram-hook session-start mode emits a system-prompt nudge instructing Claude to ask the user how to bind the current repo.

Set up your AI tools

The fastest way to wire Axgram into your AI coding tools:

axgram init

axgram init offers to log you in, then writes the session-start and session-end hooks (and, optionally, registers the MCP server) for Claude Code, Cursor CLI, Codex CLI, and Gemini CLI. Pick global (all projects) or local (current folder) scope per tool. Flags: --agent claude,cursor, --scope local|global, --no-mcp, --no-login, -y/--yes.

Transcript mining is fully supported for Claude Code today. Cursor, Codex, and Gemini hooks are wired but mining is pending transcript-format support; the hook no-ops cleanly until then.

Manual hook setup (fallback)

To configure Claude Code by hand instead, add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{ "type": "command", "command": "axgram-hook session-start --source claude" }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "axgram-hook stop --source claude --transcript ${CLAUDE_TRANSCRIPT_PATH}"
      }]
    }]
  }
}

The Stop hook counts user exchanges since the last axgram_memories_filed_away MCP tool call. When the count crosses the threshold (default 15), it exits 2 — surfacing a reminder to the model that it's time to checkpoint memories.

Configuration

| Path | Purpose | |------|---------| | ~/.axgram/credentials.json | Cached access + refresh tokens (mode 0600). | | ~/.axgram/config.json | Global default project. | | ~/.axgram/repo-bindings.json | Per-repo project bindings. | | ~/.axgram/hook-state-<project>.json | Per-project Stop-hook counter. |

Override the config directory for testing or sandboxing:

AXGRAM_CONFIG_DIR=/tmp/axgram-test axgram whoami

Worker URL

By default the CLI talks to the production worker at https://mcp.axgram.dev. To point it at a staging/dev deployment or a local worker, set AXGRAM_REMOTE_URL:

export AXGRAM_REMOTE_URL=https://mcp-stage.axgram.dev   # staging
export AXGRAM_REMOTE_URL=http://localhost:8787          # local worker

Resolution order (highest precedence first):

1. --worker-url <url> flag (per command)
2. AXGRAM_REMOTE_URL environment variable
3. AXGRAM_WORKER_URL environment variable (legacy alias; prefer AXGRAM_REMOTE_URL)
4. Default — https://mcp.axgram.dev

Development

cd cli
npm install
npm test
npm run build       # → dist/
node dist/bin/axgram.js --help

Releasing

The CLI is versioned in lock-step with the rest of Axgram from the repo-root /VERSION file — see ADR docs/decisions/0007-unified-versioning.md. Do not hand-edit cli/package.json; the unified v* tag drives the release.

1. scripts/set-version.sh X.Y.Z — bumps /VERSION + every package.json.
2. Commit (chore(release): vX.Y.Z), merge to main.
3. git tag vX.Y.Z && git push origin vX.Y.Z.
4. CI (cli-publish.yml) runs only if cli/ changed since the previous v* tag, then typecheck → test → build → npm publish via OIDC Trusted Publishing.

No NPM_TOKEN is required. The workflow exchanges a GitHub OIDC token for short-lived npm credentials against the axgram Trusted Publisher registered at npmjs.com. See docs/ops/cloud-runbook.md → "Cut a release" for the full stack release flow.

License

MIT