AgentDB

AgentDB

MCP-based agent memory management system with layered awakening.

Each agent gets its own SQLite database. An MCP server exposes tools for managing context (system prompts, todos, memories, skills, buffers, tool calls). A Flask dashboard provides a web UI and REST API for monitoring and administration.

Architecture

Worker Agent ──► MCP Server (agent_id scoped tools)
                     │
                     ▼
               SQLite per agent  ◄── Dashboard (read-only views + admin API)
                 (WAL mode)

Key design decisions:

• Layered awakening — loads ~5K tokens instead of 50K+ by selecting top priorities, top memories, skill metadata only, and buffer titles only
• Per-agent isolation — each agent has its own .db file; no cross-agent data leakage
• WAL mode — concurrent readers never block writers
• Auto-logging — AutoLoggingMCP proxy records every tool call with timing, input/output summaries, without blocking tool execution

Project Structure

agent-db/
├── agentdb_server/              # MCP server
│   ├── server.py                # Entry point, tool registration
│   ├── db.py                    # DatabaseManager (connections, migrations)
│   ├── schema.sql               # SQLite schema (7 tables)
│   ├── tool_logger.py           # AutoLoggingMCP proxy
│   └── tools/
│       ├── awaken.py            # Layered awakening (6 layers)
│       ├── todo.py              # Todo CRUD
│       ├── memory.py            # Memory store & search
│       ├── skill.py             # Skill catalog
│       ├── buffer.py            # Long document storage
│       └── tool_call.py         # Tool call logging & stats
├── dashboard/                   # Flask web app
│   ├── app.py                   # Routes (index, agent detail, admin)
│   ├── api.py                   # REST API blueprint (/api)
│   ├── models.py                # SQLAlchemy ORM models
│   └── templates/
│       ├── base.html            # Dark theme base layout
│       ├── index.html           # Agent list
│       ├── agent_detail.html    # Agent overview
│       ├── awakening_detail.html
│       └── admin.html           # Cross-agent admin overview
├── tests/
│   ├── test_core.py             # DB layer + schema tests
│   └── test_api.py              # REST API endpoint tests
└── pyproject.toml

Quick Start

Install

pip install -e ".[dashboard,dev]"

Run MCP Server

# Default agents directory: ./agents
agentdb-server

# Custom directory
AGENTDB_AGENTS_DIR=/path/to/agents agentdb-server

Run Dashboard

agentdb-dashboard
# Serves at http://localhost:5000

Run Tests

pytest tests/ -v

MCP Tools

Awakening

| Tool | Description | |------|-------------| | awaken(agent_id, include_tool_history?) | Load 6-layer context (~5K tokens) | | update_system_prompt(agent_id, content) | Create new prompt version | | get_system_prompt(agent_id) | Get active system prompt |

Awakening layers:

| Layer | Content | Budget | |-------|---------|--------| | 1 | Active system prompt | ~500 tokens | | 2 | Top 5 pending todos by priority | ~200 tokens | | 3 | Skills catalog (metadata only) | ~1000 tokens | | 4 | Top 10 memories by importance | ~3000 tokens | | 5 | Buffer references (titles only) | minimal | | 6 | Recent 20 tool calls (optional) | ~300 tokens |

Todos

| Tool | Description | |------|-------------| | add_todo(agent_id, content, priority?) | Add todo (priority 1-10) | | list_todos(agent_id, status?) | List todos, filter by status | | complete_todo(agent_id, todo_id) | Mark todo as done |

Memories

| Tool | Description | |------|-------------| | remember(agent_id, title, content, importance?, mem_type?) | Store memory (importance 0.0-1.0, type: fact/experience/insight) | | search_memories(agent_id, query, limit?) | Keyword search, ordered by importance | | get_memory(agent_id, memory_id) | Get single memory |

Skills

| Tool | Description | |------|-------------| | add_skill(agent_id, category, name, description, full_doc?) | Add to catalog | | get_skill_catalog(agent_id) | Metadata by category (no full_doc) | | load_skill(agent_id, skill_id) | Load full documentation |

Buffers

| Tool | Description | |------|-------------| | store_buffer(agent_id, title, content) | Store long document | | load_buffer(agent_id, buffer_id) | Load full content | | list_buffers(agent_id) | List titles only |

Tool Calls

| Tool | Description | |------|-------------| | log_tool_call(agent_id, tool_name, status?, ...) | Manually log external tool usage | | list_tool_calls(agent_id, tool_name?, limit?) | Query call history | | get_tool_stats(agent_id) | Per-tool stats: count, success/error rate, avg duration |

Dashboard REST API

Base URL: http://localhost:5000/api

Agents

GET    /api/agents                              # List all agents with stats

Per-Agent Resources

Each resource supports full CRUD at /api/agents/{id}/{resource}:

GET    /api/agents/{id}/memories                # List
GET    /api/agents/{id}/memories/{mid}          # Detail
POST   /api/agents/{id}/memories                # Create
PUT    /api/agents/{id}/memories/{mid}          # Update
DELETE /api/agents/{id}/memories/{mid}          # Delete

Same pattern applies to: todos, skills, buffers, system_prompts.

Tool Calls & Awakenings (read-only)

GET    /api/agents/{id}/tool_calls?tool_name=&limit=   # Call history
GET    /api/agents/{id}/tool_calls/stats                # Aggregated stats
GET    /api/agents/{id}/awakenings                      # Awakening history
GET    /api/agents/{id}/awakenings/{aid}                # Awakening detail

Examples

# List agents
curl http://localhost:5000/api/agents

# Create a memory
curl -X POST http://localhost:5000/api/agents/my-agent/memories \
  -H 'Content-Type: application/json' \
  -d '{"title": "API pattern", "content": "Use REST conventions", "importance": 0.8}'

# Get tool call stats
curl http://localhost:5000/api/agents/my-agent/tool_calls/stats

Database Schema

Each agent's SQLite database contains 7 tables:

| Table | Purpose | |-------|---------| | system_prompts | Versioned behavioral guidelines | | todos | Task items with priority (1-10) and status | | memories | Knowledge notes with importance (0.0-1.0) and type | | skills | Skill catalog with metadata + full documentation | | buffers | Long document storage | | tool_calls | Tool invocation history with timing and status | | awakenings | Snapshots of what was loaded during each awakening |

Auto-Logging

The AutoLoggingMCP proxy wraps tool registration so that every tool call is automatically recorded:

• Timing — duration in milliseconds
• Input summary — JSON with large fields truncated to 200 chars
• Output summary — truncated to 500 chars
• Silent failure — logging errors never block tool execution
• Exclusions — log_tool_call, list_tool_calls, get_tool_stats are excluded to prevent recursion

Claude Code Integration

Add to your Claude Code MCP config:

{
  "mcpServers": {
    "agentdb": {
      "command": "agentdb-server",
      "env": {
        "AGENTDB_AGENTS_DIR": "/path/to/agents"
      }
    }
  }
}

License

MIT