User's Guide

What You're Looking At

CxMS Pro adds persistent memory to your AI coding assistant. It runs locally on your machine through a set of hooks that fire automatically during your coding sessions. Those hooks are visible in your terminal, and some of their output can look unfamiliar if you're not expecting it.

This guide explains what's normal, what the messages mean, and how to configure things to your preference.

Normal Messages You'll See

Hook Status Messages

During your session, you'll see lines like:

PostToolUse:Edit hook additional context: [CxMS] ...
PreToolUse hook additional context: [CxMS] ...
SessionStart:startup hook success: [CxMS] ...

These are not errors. They are status messages from CxMS hooks reporting what they did. The word “hook” in the output is your AI tool's way of labeling where the message came from, not an indication of a problem.

“Hook Error” Labels

You may occasionally see output labeled as a “hook error” even when nothing is actually wrong. This happens because your AI tool labels any non-empty stderr output from hooks as an error. Some Node.js warnings (like ExperimentalWarning: SQLite is an experimental feature) go to stderr by default, which triggers the label.

If CxMS is still working normally, ignore these labels. A real error will include a specific failure message like “Failed to read file” or “Database connection failed.”

MCP Server Messages on Exit

When you close your session, you may see:

2 MCP servers failed

This is cosmetic. Your AI tool shuts down MCP server processes (CxMS Search, CxMS Cortex) as part of its normal exit sequence, then reports them as “failed” because they stopped. They didn't fail — they were told to stop. Your data is safe and your next session will start them fresh.

Permission Prompts

Your AI tool has its own permission system that controls which tools the AI can use without asking. CxMS hooks and MCP tools need to be in the allow list for a smooth experience.

Why You're Being Asked

If the AI asks for permission to read, edit, or write files, one of these is likely true:

1. First session: You haven't granted permissions yet. Allow them and they'll be remembered.
2. New tool pattern: A command or MCP tool the AI hasn't used before in this project.
3. Permission mode: You're running in a restricted permission mode.

How to Fix Repeated Prompts

Open your project's .claude/settings.local.json and add tools to the permissions.allow list:

{
  "permissions": {
    "allow": [
      "Bash(node:*)",
      "Bash(npm:*)",
      "Bash(git:*)",
      "mcp__cxms-cortex__cortex_query",
      "mcp__cxms-search__cxms_search"
    ]
  }
}

The AI will suggest adding specific permissions as you work. You can also grant them interactively and they'll be saved automatically.

Context Percentage

The status line shows your current context usage:

Ctx 45% Opus 4.6 (1M context)

This tells you how much of the AI's memory window your current session has consumed.

What to do at 80%: Save your work, note where you left off, and start a new session. CxMS saves your session state automatically so the next session can pick up where you left off.

Session Lifecycle

A typical CxMS Pro session looks like this:

1. Session Start — CxMS loads your memory, checks for updates, reads your session file
2. Working — Hooks track context usage, save breadcrumbs, monitor for important patterns
3. Checkpoints — Every ~30 tool uses, CxMS saves a checkpoint so work isn't lost
4. Session End — Memory is updated, session state is saved, background tasks run

You don't need to do anything special. CxMS manages this automatically.

The Memory System

CxMS Pro remembers things across sessions. It uses a confidence-based tier system:

Memories are automatically extracted from your conversations, consolidated during idle time, and queried when relevant context is needed. You can view and manage memories through the Cortex MCP tools.

Installation and Your Existing Files

CxMS Pro is designed to work alongside your existing project setup, not replace it.

• Your CLAUDE.md (or .cursorrules, etc.) is never overwritten. If you already have a rules file, CxMS Pro appends its memory instructions to the end. Your existing instructions are preserved.
• If the file already has CxMS instructions, the installer skips it entirely (no duplicates).
• If no rules file exists, one is created with only the CxMS memory instructions.
• The cxms-pro/ directory is installed inside your project. If it already exists, the installer asks before overwriting.

Telemetry

CxMS Pro collects minimal, anonymized usage telemetry to help improve the product. No code, file names, file contents, memory content, prompts, or AI responses are ever transmitted.

What IS collected: tool usage counts, session duration, memory statistics (aggregate counts only), Node.js version, and OS platform.

Common Questions