How to use the agentmemory Setup and Diagnostics agent skill

What the agentmemory-config skill makes the agent do

An agent skill is a folder with a SKILL.md file that gives an AI agent specific instructions for one job. This skill covers setup and diagnostics for agentmemory: its MCP connection, environment variables, ports and feature flags. When it is installed, the agent can check whether the memory server is running, read settings from environment files, explain which features are on or off by default, and help turn on optional features such as LLM compression or context injection.

The skill is meant for getting started and troubleshooting, not everyday memory use. It is listed as not user-invocable, so you normally trigger it by describing your problem in ordinary words, and the agent decides to use it.

• Checks the agentmemory MCP connection and daemon status
• Reads settings from ~/.agentmemory/.env
• Explains default feature states and why a feature is off
• Helps enable optional features after you choose a provider

How do you install the agentmemory-config skill?

Download the skill ZIP from this directory page and unzip it into one of two places. For a personal setup for all projects, use ~/.claude/skills/. For a single project, put it in that project's .claude/skills/ folder. Restart your agent session afterwards so it picks up the new skill.

If you use the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

The skill needs Node.js 20 or newer, and agentmemory itself installed with its local daemon running. The skill does not install agentmemory for you.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How do you check the agentmemory connection first?

The skill tells the agent to start with the connection before changing anything. If the host exposes the agentmemory status resource, the agent reads it; otherwise it calls memory_sessions without creating any data. A successful handshake alone does not prove the daemon is running, so the agent also checks the daemon.

If the check fails, the agent looks at Node.js 20+ and runs agentmemory status. On a source checkout it uses node dist/cli.mjs status after building. Keep the runtime running while you use the plugin.

• Codex's plugin already supplies MCP; agentmemory connect codex is the MCP-only alternative
• If both are configured, the agent explains the duplicate and lets you choose which to keep
• Hook support is checked with /hooks in Codex before any automatic capture is promised

How do you enable optional features like compression and context injection?

Basic keyword recall needs no API key. Richer features are opt-in. After you choose an LLM or embedding provider, set its key locally without printing it, then enable the features you want in ~/.agentmemory/.env, one KEY=value per line with no export prefix. Restart the server after any change.

Per-observation LLM compression and Claude-style context injection are both off by default. Local embeddings also need explicit configuration and model downloads, so the agent will not promise vector search until it is enabled. Enabled external model providers can receive selected content, so the agent explains that boundary before you turn them on.

• AGENTMEMORY_AUTO_COMPRESS=true turns on per-observation LLM compression
• AGENTMEMORY_INJECT_CONTEXT=true turns on Claude-style hook injection
• Consolidation runs when an LLM provider is configured, unless CONSOLIDATION_ENABLED=false or AGENTMEMORY_PROVIDER=noop
• Structured slots need AGENTMEMORY_SLOTS=true; slot reflection also needs AGENTMEMORY_REFLECT=true

What are the default ports, auth and remote URL rules?

REST defaults to port 3111, the viewer to 3113, and the internal engine WebSocket to 49134. Use --port <N> or --instance <N> to select another local runtime. For a custom port, the MCP host needs AGENTMEMORY_URL passed through its environment, followed by a restart of the MCP server.

Local authentication is automatic. The bridge uses a host AGENTMEMORY_SECRET first, then the secret in ~/.agentmemory/.env, then the daemon-generated ~/.agentmemory/secret. Remote URLs require an explicit host secret, and local files are never forwarded. Non-loopback URLs must use HTTPS for authenticated requests; HTTP is allowed only for localhost, 127.0.0.0/8 or [::1].

• REST API: 3111 by default
• Viewer: 3113 by default
• Engine WebSocket: 49134 by default
• AGENTMEMORY_CREDENTIAL_MODE=explicit disables local credential discovery