AI代理认知框架平台

ego-mcp

Cognitive scaffolding platform that gives AI agents persistent personality, memory, and emotions.

ego-mcp is a monorepo containing an MCP (Model Context Protocol) server that enables LLM agents to maintain consistent personality, memory, and emotions across sessions, along with a telemetry dashboard for real-time observability.

Key Features

• Persistent Memory — ChromaDB-based semantic search + Hopfield pattern completion for associative recall
• Abstract Desire System — Nonlinear computation with emotion/memory modulation for intrinsic motivation
• Cognitive Scaffolding — Tool responses include thinking frameworks, not just data, guiding natural AI behavior
• Relationship Model — Theory of Mind framework for structuring relationships with others
• Self-Maintaining Notions — Reinforcement, decay, duplicate merge, person association, and related-notion links
• Temporal & Relational Sense — Anticipation of future events, absence/reunion awareness, ripening open questions, and implicit protection of precious memories
• Telemetry Dashboard — Real-time visualization of tool usage, emotion trends, and logs

Repository Structure

ego-mcp/
├── ego-mcp/            # MCP server (Python)
├── dashboard/          # Telemetry dashboard
│   ├── src/            #   Backend (FastAPI + TimescaleDB + Redis)
│   └── frontend/       #   Frontend (React + Vite + TypeScript)
├── design/             # Design documents
└── .github/workflows/  # CI

ego-mcp

MCP server providing cognitive capabilities to AI agents.

Tools

Surface Tools — directly used by the agent:

Backend Tools — guided by surface tools:

Setup

cd ego-mcp
uv sync --extra dev

Set environment variables for the embedding provider:

# Gemini (default)
export GEMINI_API_KEY="your-gemini-api-key"

# OR OpenAI
export EGO_MCP_EMBEDDING_PROVIDER="openai"
export OPENAI_API_KEY="your-openai-api-key"

Run

cd ego-mcp
uv run python -m ego_mcp

Connecting to an MCP Client

Example configuration for Claude Desktop or other MCP-compatible clients:

{
  "mcpServers": {
    "ego": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ego-mcp", "python", "-m", "ego_mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

See ego-mcp/README.md for full documentation including environment variables and workspace sync.

Dashboard

Telemetry dashboard for observing ego-mcp in action.

• Now tab: Summary cards + real-time charts + event feed
• History tab: Tool usage counts, notion maintenance history, network links, and parameter trends
• Logs tab: Live tail of masked logs

Run (Docker Compose)

cd dashboard
cp .env.example .env
# Memory Network / Notions も使う場合は ego-mcp の data dir を設定
# export DASHBOARD_EGO_MCP_DATA_DIR="/absolute/path/to/ego-mcp-data"
docker compose up --build

• Backend: http://localhost:8000
• Frontend: http://localhost:4173

See dashboard/README.md for full documentation.

Development

Prerequisites

• Python 3.14
• uv
• Node.js 24 (dashboard frontend)
• Docker + Docker Compose (dashboard)

Test & Lint

# ego-mcp
cd ego-mcp
GEMINI_API_KEY=test-key uv run pytest tests -v
uv run ruff check src tests
uv run mypy src tests

# dashboard backend
cd dashboard
uv run pytest -v
uv run ruff check src tests
uv run mypy src tests

# dashboard frontend
cd dashboard/frontend
npm ci
npm run lint
npm run test
npm run build

Acknowledgments

• embodied-claude by @kmizu

License

MIT