CodeArchitect MCP Docs

Never let AI ruin your codebase again - Context augmentation for agents

CodeArchitect MCP gives coding agents deep system design intelligence. It increases context window and reduces AI hallucinations by providing agents with structured chat storage and workflow assistance, decreasing token usage of most coding agents by at least 40%.

Get Started

Install CodeArchitect MCP and configure it for your coding agent in minutes.

Start Using CodeArchitect - It’s That Easy!

After installation, simply ask your AI assistant:

use codearchitect

This will show you all available features and how to use them. That’s it! No complex commands to remember.

Example Prompts

Get help:

use codearchitect

Save a conversation (recommended workflow):

1. Export chat from Cursor/VS Code to ~/.codearchitect/exports/
2. Say: use codearchitect store_session
3. Tool auto-detects export file and saves it

Save with a specific topic:

use codearchitect store_session topic: "authentication implementation"

Save to project folder too:

use codearchitect store_session projectDir: "/path/to/project"

Retrieve a saved session:

use codearchitect get_session

Get a specific session:

use codearchitect get_session authentication-implementation

Search across sessions:

use codearchitect search_session "authentication"

Search with date filter:

use codearchitect search_session "database" date: "2025-01-20"

Storage Locations

Main location (always): ~/.codearchitect/sessions/

• Windows: C:\Users\YourName\.codearchitect\sessions\
• Linux/Mac: ~/.codearchitect/sessions/

Export folder (for auto-detection): ~/.codearchitect/exports/

• Export chats here for automatic detection

Optional project folder: project/.codearchitect/sessions/

• Only if projectDir parameter is specified

Folder Structure

Sessions are automatically organized in readable folders:

~/.codearchitect/sessions/
└── 2025-11-18/
    ├── authentication-implementation/
    │   ├── summary.md          # Quick summary + key points
    │   └── full.md             # Complete conversation
    └── database-migration/
        ├── summary.md
        └── full.md

Why CodeArchitect MCP?

Solves the problem of losing valuable AI conversations. Important discussions with AI assistants often disappear, especially during system design and architecture work.

Preserve Knowledge

Save conversations as searchable markdown files

Organize Thoughts

Auto-organized by date and topic folders

Searchable

Search with grep, IDE, or git

Zero Configuration

Works out of the box

Quick Start

1. Install

   npm install -g codearchitect-mcp
   
2. Configure

   See Installation Guide for your IDE (Cursor, VS Code, Claude Desktop, Windsurf, Continue.dev, Cline).

3. Start Using

   Just say:

   use codearchitect
   

   Your AI assistant will show you everything you can do!

Current Features (v0.1.8)

• ✅ codearchitect_help - Discover available features with use codearchitect
• ✅ Session Storage - Save AI conversations in topic-named folders (summary.md + full.md)
• ✅ Session Retrieval - Get and list stored sessions with TOON format support (~40% token reduction)
• ✅ Session Search - Full-text search across all sessions with relevance scoring and context snippets
• ✅ Auto-Organization - Organized by date in readable topic folders
• ✅ Smart Topics - Extracts topics from conversations with redundant suffix removal
• ✅ Automatic Export Detection - Auto-detects Cursor/VS Code export files from ~/.codearchitect/exports/
• ✅ VS Code JSON Support - Full support for VS Code’s JSON export format
• ✅ Export Filename Matching - Match specific export files by pattern
• ✅ Reliable Storage - Always saves to ~/.codearchitect/sessions/ (home directory)
• ✅ Optional Project Save - Optionally save to project folder with projectDir parameter
• ✅ Token Optimization - TOON format reduces token usage by ~40% for LLM interactions
• ✅ Date Filtering - Filter search results by specific date or date range
• ✅ Result Limiting - Limit number of search results returned

Roadmap

• 🔜 Session Management - Delete, export sessions
• 🔜 Architecture Tools - Analyze, document, review designs
• 🔜 Workflow Tools - Track decisions, manage tech debt

See Tools & Features for details.

Links

• 📦 npm: codearchitect-mcp
• 💻 GitHub: tairqaldy/codearchitect-mcp
• 👨‍💻 Author: Tair Kaldybayev