Axom MCP Server

Axom is a Model Context Protocol (MCP) server that provides persistent memory, tool abstraction, and chain-of-thought for AI agents.

Core Features

• Persistent Memory: Store and retrieve context across sessions using the Axom (SQLite) database.
• Tool Abstraction: Unified interface for memory, execution, analysis, discovery, and transformation.
• Chain Reactions: Execute tool sequences where outputs feed into the next step.
• AI-Powered Classification: Automatically categorizes memories by type and importance.

Quick Start

Axom runs as stdio MCP - your IDE spawns it automatically. No manual server startup needed.

Prerequisites

• Python 3.11+
• SQLite (included with Python)
• Git

Installation

Linux / macOS / WSL / Windows (Native)

Requires Git Bash, PowerShell, or a make provider.

git clone https://github.com/PugzUI/axom-mcp.git
cd axom-mcp
make install

What make install does:

1. Installs Python dependencies.
2. Installs Axom in editable mode (pip install -e .).
3. Creates .env from .env.example.
4. Configures all detected agents (Cursor, Trae, etc.).
5. Installs Axom rules and skills for each agent.

Verification

make test      # Run tests

Post-Install Check

Verify the local command is available:

command -v axom-mcp

Verify MCP initialization against the installed server:

python3 - <<'PY'
import asyncio
from mcp import ClientSession
from mcp.client.stdio import stdio_client, StdioServerParameters

async def main():
    params = StdioServerParameters(command="axom-mcp", args=[])
    async with stdio_client(params) as (read_stream, write_stream):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            tools = await session.list_tools()
            print("tool_count:", len(tools.tools))

asyncio.run(main())
PY

Client Configuration

make install automatically configures MCP for detected agents. The installer uses the best available command:

1. axom-mcp (if in PATH)
2. axom (if in PATH)
3. python -m axom_mcp.server (fallback)

See docs/agents/INDEX.md for detailed agent configuration.

For Zed, ~/.config/zed/settings.json should contain:

"context_servers": {
  "axom": {
    "command": "axom-mcp",
    "args": []
  }
}

Tools

Axom provides five core MCP tools:

• axom_mcp_memory: Store and retrieve persistent context.
• axom_mcp_exec: File operations and shell commands with chaining.
• axom_mcp_analyze: Code analysis and debugging.
• axom_mcp_discover: Map environment and capabilities.
• axom_mcp_transform: Convert data between formats.

Documentation

• Architecture - System design and data flow.
• Tool Reference - Detailed tool parameters.
• Agent Guide - How to use Axom with AI agents.
• Troubleshooting - Common issues and fixes.