Cortex Ast

CortexAST 🧠⚡

> The AI-Native Code Intelligence Backend for LLM Agents > Pure Rust · MCP Server · Semantic Code Navigation · AST Time Machine · Self-Evolving Wasm Parsers

[](https://www.rust-lang.org) [](./LICENSE) [](./CHANGELOG.md)

---

What is CortexAST?

> 👁️ CortexAST is the "eyes" — read-only code intelligence. For write/execute capabilities, see the companion cortex-act project (the "hands").

CortexAST is a production-grade MCP (Model Context Protocol) server that gives AI coding agents (Claude, Gemini, GPT-4o, etc.) the ability to:

• Navigate codebases semantically — find symbols, blast-radius analysis, cross-file propagation checklists
• Evolve itself — download and hot-reload WebAssembly language parsers at runtime (Go, PHP, Ruby, Java, …)
• Time-travel your codebase — Chronos snapshot system for pre/post-refactor AST-level comparison
• Search local memory — hybrid semantic + keyword search over your codebase history

> ✋ To edit files, run commands, or patch configs, use cortex-act instead.

---

Feature Modules

1. 🔭 cortexcodeexplorer

Codebase explorer. Use INSTEAD of ls/tree/find/cat. Two modes: map_overview (fast symbol map, near-zero tokens — run first on any repo) and deep_slice (token-budgeted XML with function bodies, vector-ranked by query). Use mapoverview to orient; deepslice to get code for editing.

2. 🎯 cortexsymbolanalyzer

AST symbol analysis. Use INSTEAD of grep/rg. Actions: read_source (extract exact source of a symbol from a file — do this before editing), find_usages (all call/type/field sites), find_implementations (structs implementing a trait), blast_radius (callers + callees — run before rename/delete), propagation_checklist (exhaustive update checklist for shared types).

3. ⏳ cortex_chronos

AST snapshot tool for safe refactors. Workflow: save_checkpoint (before edit) → edit → compare_checkpoint (verify). Use instead of git diff — AST-level, ignores formatting noise. Actions: save_checkpoint, list_checkpoints, compare_checkpoint, delete_checkpoint.

4. 🛠️ run_diagnostics

Run compiler diagnostics (cargo check / tsc / gcc). Call after any code edit to catch errors before proceeding. Returns file, line, code, message — structured for targeted fixes.

5. 🧠 cortexmemoryretriever

Search past agent decisions in global memory (semantic + keyword hybrid). Requires CortexSync. Call BEFORE any research or exploration — the answer may already be cached. Returns ranked entries: intent, decision, tags, files_touched.

6. 📋 cortexgetrules

Fetch codebase AI rules for the current context. Requires CortexSync. Returns merged rules filtered by file_path (frontend/backend/db context). Call before starting any task in a new project.

7. ✨ cortex_remember

Save task outcome to permanent global memory. Requires CortexSync. Call at END of every task. intent+decision must be ≤200 chars each. For long artifacts write a file first and pass path via heavy_artifacts.

8. 🌍 cortexlistnetwork

List all AI-tracked codebases (Requires CortexSync network). Use to discover target_project IDs for cross-project operations.

9. 🌐 cortexmanageast_languages

Manage Wasm grammar parsers for non-core languages. Core (always active): rust, typescript, python. Call status to see active/available languages. Call add with languages[] to download and hot-reload parsers from GitHub tree-sitter releases. Available: go, php, cpp, c, c_sharp, java, ruby, dart.

---

Ecosystem Requirement: CortexSync 🧠

For full functionality, CortexSync (the "Brain") must be running in the background.

| Tool | Dependent on CortexSync? | Why? | |---|---|---| | cortex_remember | Yes | Persists task outcomes to the global journal. | | cortex_memory_retriever| Yes | Performs semantic vector search over past decisions. | | cortex_get_rules | Yes | Fetches centralized rules from the synchronized rule engine. | | cortex_list_network | Yes | Reads the global network map of codebases. | | cortex_code_explorer | No | Local AST analysis. | | cortex_symbol_analyzer | No | Local AST analysis. |

If cortex-sync is offline, these tools will strictly return a graceful warning without interrupting the agent's workflow.

---

---

Quick Start

Prerequisites

• Rust 1.80+
• Ollama or LM Studio running locally (optional, for Auto-Healer)

Build & Run

git clone https://github.com/DevsHero/CortexAST
cd CortexAST
cargo build --release

# Run as MCP server (stdio)
./target/release/cortexast

MCP Config (~/.cursor/mcp.json or Claude Desktop)

{
  "mcpServers": {
    "cortexast": {
      "command": "/path/to/cortexast",
      "args": []
    }
  }
}

---

---

Usage Examples

Semantic Explorer — Bird's-eye view of a project

{
  "name": "cortex_code_explorer",
  "arguments": {
    "action": "map_overview",
    "target_dir": "."
  }
}

Symbol Search — Find all usages across the repo

{
  "name": "cortex_symbol_analyzer",
  "arguments": {
    "action": "find_usages",
    "symbol_name": "AuthService",
    "target_dir": "."
  }
}

Time Travel — Compare AST after refactor

{
  "name": "cortex_chronos",
  "arguments": {
    "action": "compare_checkpoint",
    "symbol_name": "login",
    "tag_a": "pre-refactor",
    "tag_b": "__live__"
  }
}

Self-Evolving Wasm Language Support

| Always Available | Downloadable on Demand | |---|---| | Rust, TypeScript/JS, Python | Go, PHP, Ruby, Java, C, C++, C#, Dart |

# Agent calls this automatically when it detects a new language:
cortex_manage_ast_languages { "action": "add", "languages": ["go", "dart"] }

---

Development

# Run all unit tests
cargo test

# Check (no link)
cargo check

---

## Architecture

CortexAST (binary) └── src/ ├── server.rs # MCP stdio server — all tool schemas + handlers ├── inspector.rs # LanguageConfig, LanguageDriver, Symbol, runquery ├── grammarmanager.rs # Wasm download + hot-reload (GitHub releases) ├── vectorstore.rs # model2vec embeddings + cache invalidation ├── chronos.rs # AST snapshot time machine (Chronos) ├── memory.rs # globalmemory.jsonl journal client └── project_map.rs # Network map for multi-repo roaming

## License

MIT — See [LICENSE](./LICENSE)

---

*Built with ❤️ in Rust · Semantic precision for the AI age*

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cortex-works](https://github.com/cortex-works)
- **Source:** [cortex-works/cortex-ast](https://github.com/cortex-works/cortex-ast)
- **License:** MIT

Install and usage instructions live in the source repository linked above.