🧠 AI-Memory

The Open-Source Multi-AI Orchestration System

Turn any IDE into a coordinated team of AI agents: Claude, Gemini, DeepSeek, and Local Models working together.

---

AI-Memory is a revolutionary file-based AI orchestration framework. It transforms a simple folder (_AI_MEMORY/) into a command center where different AI models take on specialized roles (CTO, Security Auditor, Builder, Code Reviewer) to collaborate on your project without stepping on each other's toes.

No complex infrastructure. No expensive SaaS lock-in. Just standard markdown files, local scripts, and a built-in Model Context Protocol (MCP) server that plugs directly into modern AI IDEs like Claude Code, Cursor, Windsurf, and Zed.

📖 Why I Built This

As a solo founder, I needed a team. I needed a CTO to design systems, a Security Auditor to check my code, a UX expert to refine interfaces, and a tireless builder to write boilerplate.

I couldn't afford to hire them, but I realized I could orchestrate them. AI-Memory is the exact system I built to seamlessly coordinate 5 different AI models (Claude, Gemini, DeepSeek, Kimi, and local Gemma) to act as my engineering department. They read from the same memory, they respect the same rules, and they pass the baton perfectly.

✨ Features

• 🤖 Multi-Agent Escalation Ladder: Start with free local models (Gemma) for simple tasks and compress context before seamlessly escalating to DeepSeek, Gemini, or Claude for complex decisions.
• 🔌 Built-in MCP Server: Exposes your project's memory, context, and decision logs directly to any MCP-capable IDE via standardized tools.
• 📁 File-Based State Management: Completely transparent orchestration. Everything from Session State to Architectural Decisions (ADRs) is stored in readable Markdown.
• 🛡️ Specialized Claude Sub-Agents: Pre-configured prompts for security-auditor, system-architect, design-reviewer, qa-tester, and more.
• 🚀 One-Click Setup: Designed to be used as a GitHub Template for instant setup on new projects.

---

🛠️ Quick Start

1. Use as a Template

1. Click the Use this template button at the top right of this repository.
2. Clone your new repository locally.
3. Run the init script to set up your IDE adapters:

   bash _AI_MEMORY/init.sh

2. Connect the MCP Server to your IDE

The included MCP server allows AI agents to intelligently read from and write to your project's memory.

Build the Server:

cd mcp-server
npm install
npm run build

For Claude Code:

claude mcp add ai-memory -- node /absolute/path/to/mcp-server/dist/index.js

For Cursor / Windsurf / Zed (Add to MCP Config JSON):

{
  "mcpServers": {
    "ai-memory": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "AI_MEMORY_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

---

🧰 Available MCP Tools

When the server is connected, your IDE gains access to the following superpowers:

Tool	Capability
🧠 memory_get_context	Fetches the Tier-1 startup bundle (profile + state + rules) for instant context loading.
📖 memory_read_file	Sandboxed reading of any file within the _AI_MEMORY system.
🗺️ memory_list_files	Generates a structural map of the entire memory system.
💾 memory_update_session_state	Writes a concise end-of-session snapshot for the next agent.
📝 memory_log_activity	Appends completed tasks to the master activity log.
⚖️ memory_add_decision	Generates and appends auto-numbered Architectural Decision Records (ADRs).
❓ memory_add_clarification	Queues ambiguity questions for the human developer instead of hallucinating.
🛡️ memory_check_dependency	Validates packages against the project's approved registry gate.

---

🏗️ Architecture

Inside the _AI_MEMORY/ directory, you'll find:

• agents/: Core system agents and routing logic.
• claude_subagents/: Specialized task-runners.
• discovery/: Network and repository scouting tools.
• hooks/: Git hooks to ensure AI policies are enforced on commit.
• logs/: Transparent, chronological history of AI actions and state changes.

---

🤝 Contributing

Contributions are welcome! If you build a new agent profile, optimization script, or IDE adapter, please submit a PR.

📄 License

This project is licensed under the MIT License.

Designed for the autonomous developer. Built by HM Noman Riaz.