reflective-agent-architecture

Reflective Agent Architecture (RAA) is an MCP server that orchestrates a metacognitive, reflective agent system. It combines associative memory, a metacognitive Director for monitoring and search, and a Ruminator for diagrammatic reasoning to reframe goals and resolve confounds. The server exposes tools and components that interact with a local graph database (Neo4j), an LLM backend (via Ollama), and a configurable environment. To use it, deploy the server with the MCP runner (uv) and connect your client (e.g., Claude Desktop or any MCP-compatible frontend) to the reflective-agent-architecture server in your MCP client config. The system can spawn specialized sub-agents (e.g., Debaters, Explorers) through COMPASS integration to tackle complex planning tasks or multi-step reasoning tasks. You can provide a project prompt that leverages the RAA Agent Protocol to guide the agent through problem solving, decision making, and insight-driven reframing.

Once running, you’ll interact with the server by sending tasks or prompts that the Director will monitor for entropy (uncertainty) and, when high, trigger a search through the associative memory manifold to reframe goals. The Ruminator will analyze knowledge graphs for non-commutative patterns and infer missing relations, while the Precuneus fuses outputs from the memory, metacognitive monitoring, and goal representations into a coherent action plan. Advanced usage includes delegating complex tasks to COMPASS for multi-step reasoning and metacognitive planning, with options to force time gating for synthesis auto-resolution when data is sufficient in-house.

Prerequisites:

• Git
• Python environment with uv (uvx) support installed or the uv runner for your platform
• Docker (optional for Neo4j or other services)
• Ollama (LLM backend) and an appropriate model
• Neo4j database (Desktop or Docker)

Step-by-step installation:

1. Clone the repository git clone https://github.com/angrysky56/reflective-agent-architecture.git cd reflective-agent-architecture

2. Install and configure runtime

   • If using uv (Python-based): install uv with your Python environment. For example: uv sync --extra server
   • Ensure Node.js is not strictly required unless you plan to use a Node wrapper; this server is configured to run under uv.

3. Install and configure dependencies

   • Ollama: follow instructions at https://ollama.com/ to install and start the LLM backend.
   • Neo4j: install Neo4j Desktop or run Neo4j in Docker and note the password for the neo4j user.
   • Create an example environment file from the template if provided (e.g., cp .env.example .env) and set NEO4J_PASSWORD and any model selections you want.

4. Configure MCP client connection

   • Use the provided MCP client configuration to point to this server. Example (adjust path): mcpServers: reflective-agent-architecture: command: uv args: - --directory - /ABSOLUTE/PATH/TO/reflective-agent-architecture - run - raa-server

5. Run the server

   • Start the MCP runner and the raa-server target as defined in the config. Ensure Ollama and Neo4j are running and accessible.

6. Verify connectivity

   • Connect via your MCP client with the configured JSON path and test with a simple prompt to observe Director monitoring, entropy triggers, and goal reframing flow.

Tips and caveats:

• Environment variables: Keep NEO4J_PASSWORD secure; store in a .env file and reference it through the MCP config if possible.
• Model selection: Adjust LLM_MODEL and EMBEDDING_MODEL in your environment to tune performance and memory usage.
• If you see high entropy but no effective reframing, validate the connectivity to Neo4j and Ollama; ensure the Ollama model is properly downloaded (e.g., qwen3:latest).
• COMPASS integration: Delegating to COMPASS can offload complex planning tasks; use force_time_gate: True when you want the synthesis step to resolve with available tools without external data.
• Logs and debugging: Monitor logs from uv/mcp and the raa-server; typical issues include path misconfigurations, missing environment variables, or inaccessible services (Neo4j, Ollama, etc.).
• Security: Limit access to the Neo4j instance and the MCP configuration to trusted clients; use environment-based access controls where possible.