aspectgraph-mcp

AspectGraph memory for MCP clients and agent hooks. The package ships both a stdio MCP server and a hook-safe CLI for deterministic context recall.

Usage

# Start the stdio MCP server (default, no subcommand)
npx -y aspectgraph-mcp

# Install MCP + read-path hooks for a client (claude, codex, cursor)
npx -y aspectgraph-mcp install claude
npx -y aspectgraph-mcp install codex
npx -y aspectgraph-mcp install cursor
npx -y aspectgraph-mcp uninstall cursor

# Diagnose configuration (credentials, workspace, client config, API)
npx -y aspectgraph-mcp doctor

One-command install (setup tokens)

The AspectGraph web app can mint a short-lived, single-use setup token and show a ready-to-run command, so you never copy an API key by hand:

npx -y aspectgraph-mcp install claude --setup-token ag_setup_xxx --api-url https://your-api.example.com

The installer exchanges the token for scoped config, writes the client config with the ${ASPECTGRAPH_API_KEY} placeholder (no secret committed), and saves the real key to a git-ignored .aspectgraph/credentials file. The CLI loads that file into the environment at startup, so hooks and the MCP server authenticate automatically. Tokens are workspace- and client-scoped, expire quickly, and are rejected on reuse. Manual ASPECTGRAPH_API_KEY setup remains fully supported as a fallback.

Configuration

Set these in your shell environment (the installer never writes secrets into committed files):

| Variable | Required | Description | | --- | --- | --- | | ASPECTGRAPH_API_KEY | yes | API key used for auth (or ASPECTGRAPH_BEARER_TOKEN). | | ASPECTGRAPH_WORKSPACE_ID | yes for hooks | Workspace to recall from. | | ASPECTGRAPH_API_URL | no | API base URL (default http://127.0.0.1:8787). |

Claude Code installer

aspectgraph-mcp install claude configures Claude Code for deterministic recall:

• Merges .mcp.json with an aspectgraph MCP server entry. The API key is referenced as ${ASPECTGRAPH_API_KEY} so the literal secret is never written into this committed file.
• Merges .claude/settings.local.json (local, git-ignored) with two hooks:
  • SessionStart → aspectgraph-mcp context-hook (injects recent workspace memory)
  • UserPromptSubmit → aspectgraph-mcp recall-hook (recalls memory relevant to the prompt)

The installer:

• Preserves all unrelated MCP servers, permissions, and hooks.
• Is idempotent — re-running never duplicates entries.
• Creates timestamped backups (<file>.bak-<timestamp>) before editing.
• Refuses to overwrite a config file that contains invalid JSON.

Run aspectgraph-mcp uninstall claude to remove only AspectGraph-owned entries.

Codex installer

aspectgraph-mcp install codex configures Codex with the same guarantees (preserve unrelated config, idempotent, timestamped backups, no committed secrets):

• Merges .codex/config.toml with an [mcp_servers.aspectgraph] stdio server (API key referenced as ${ASPECTGRAPH_API_KEY}). Only the AspectGraph table block is edited; the rest of the file is left byte-for-byte intact.
• Merges .codex/hooks.json with SessionStart and UserPromptSubmit hooks. Hooks live only in hooks.json (never also inline in config.toml) to avoid Codex duplicate-source warnings.

Codex trust: Codex runs project hooks only after you trust the project and its hooks. After installing, open Codex in the repo and approve the project/hooks, then verify the server appears under /mcp.

Run aspectgraph-mcp uninstall codex to remove only AspectGraph-owned entries.

Cursor installer

aspectgraph-mcp install cursor configures Cursor with MCP plus an always-on project rule (same preserve/idempotent/backup/no-secret guarantees):

• Merges .cursor/mcp.json with the aspectgraph MCP server (API key referenced as ${ASPECTGRAPH_API_KEY}).
• Writes .cursor/rules/aspectgraph.mdc, a short always-on rule that nudges the agent to search AspectGraph before project answers and to save durable decisions/facts after confirmation.

Support level: Cursor integration is MCP + a rule, not deterministic lifecycle recall. Cursor has no verified hook API, so unlike Claude Code and Codex it cannot guarantee recall on every prompt — the rule only nudges the agent. uninstall cursor removes the server entry and deletes the rule file only while it is still AspectGraph-owned.

Hooks

Hook subcommands read one lifecycle JSON object on stdin and emit Claude Code-compatible hookSpecificOutput.additionalContext. They fail open: malformed input, missing credentials, API errors, and timeouts all result in no output and a clean exit, so a recall failure never blocks a prompt.

Capture (opt-in)

capture-hook durably saves significant session memory. It is off by default and conservative by design:

• Enable with --capture at install time (wires PreCompact/PostCompact/Stop hooks for Claude Code and Codex) and ASPECTGRAPH_CAPTURE=true in the hook environment. Both are required, so capture is always a deliberate choice.
• Saves only significant turns — a compact summary, or an explicit "remember/save/note this" request — as structured objects, never raw transcripts.
• Redacts obvious secrets (bearer tokens, provider keys, KEY=VALUE secrets) and caps saved text length.
• Dedupes by a stable workspace+repo+type+content key, so the same decision is not saved twice across compact/resume/stop.
• Fails open: a capture error never blocks the client.