AgentOS — Persistent Cognitive Layer for AI Agents

AgentOS is an MCP (Model Context Protocol) server that gives any compatible AI agent a persistent cognitive layer: long-term memory, goal tracking, self-reflection, and autonomous background monitoring.

It is not a standalone agent. It is a skill that agents like Claude Code, Hermes, or any MCP-compatible agent can connect to and use.

Without AgentOS:   Agent ←→ Tools
With AgentOS:      Agent ←→ AgentOS (Memory · Goals · Reflection · Insights) ←→ Tools

---

Features

• Persistent Memory — semantic search across sessions using local embeddings (no API needed)
• Goal Management — track objectives with priority, urgency, deadlines, and progress
• Self-Reflection — log actions and outcomes, detect repeated failures and success patterns
• Background Daemon — runs independently, monitors agents, and generates proactive insights
• Model-agnostic — works with any agent that supports MCP
• Fully offline — no external API calls required

---

Architecture

┌─────────────────────────────────────────┐
│              AI Agent                   │
│  (Claude Code / Hermes / any MCP agent) │
└────────────────┬────────────────────────┘
                 │ MCP (stdio)
┌────────────────▼────────────────────────┐
│           MCP Server (server.py)        │
│                                         │
│  memory_store      memory_search        │
│  goal_add          goal_get_active      │
│  reflection_log    reflection_analyze   │
│  context_get_snapshot                   │
└────────────────┬────────────────────────┘
                 │ SQLite + ChromaDB
┌────────────────▼────────────────────────┐
│         Background Daemon (daemon.py)   │
│                                         │
│  • every 30 min → reflection analyzer  │
│  • every 60 min → goal monitor         │
│  • every  6 hrs → self maintenance     │
│  • every 24 hrs → memory decay         │
└─────────────────────────────────────────┘

---

Installation

Requirements: Python 3.11+

git clone https://github.com/your-username/agentos.git
cd agentos

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate

pip install -r requirements.txt

cp .env.example .env

The first run will automatically download the embedding model (~90 MB).

---

Running

Start both processes — each in its own terminal:

# Terminal 1 — MCP Server (talks to the agent)
python server.py

# Terminal 2 — Background Daemon (runs continuously)
python daemon.py

The daemon is optional but required for the "semi-alive" behavior (proactive insights, memory decay, goal alerts).

---

Connecting to an Agent

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "agentos": {
      "command": "python",
      "args": ["/absolute/path/to/agentos/server.py"]
    }
  }
}

Restart Claude Desktop. A 🔨 icon will appear confirming the connection.

Claude Code

claude mcp add-json agentos '{
  "command": "python",
  "args": ["/absolute/path/to/agentos/server.py"]
}'

Verify with /mcp inside Claude Code.

---

Available MCP Tools

Memory

Tool	Description
memory_store	Store a new memory with type and importance
memory_search	Semantic search across memories
memory_list	List recent memories
memory_update_importance	Update a memory's importance score
memory_delete	Delete a specific memory

Goals

Tool	Description
goal_add	Add a new goal with priority, urgency, deadline
goal_get_active	Get active goals sorted by composite priority
goal_update_progress	Update progress on a goal
goal_update_status	Change goal status
goal_list	List goals by status

Reflection

Tool	Description
reflection_log	Log an action and its outcome
reflection_analyze	Detect patterns from recent logs
reflection_get_patterns	Retrieve stored patterns
reflection_get_summary	Performance summary over N days

Context

Tool	Description
context_get_snapshot	Unified cognitive state (memories + goals + insights + daemon status)

---

Recommended Agent Workflow

1. Session starts  → call context_get_snapshot
                     (loads memories, goals, daemon insights)

2. During work     → call memory_store for important information
                     call reflection_log after each significant action

3. New objective   → call goal_add

4. Session ends    → call reflection_analyze to update patterns

---

Configuration

All settings are in .env (copy from .env.example):

Variable	Default	Description
DATABASE_URL	sqlite:///./agentos.db	SQLite database path
CHROMA_PERSIST_DIR	./chroma_store	ChromaDB persistence directory
EMBEDDING_MODEL	all-MiniLM-L6-v2	Local sentence-transformers model
MEMORY_DECAY_RATE	0.01	Daily decay rate for unaccessed memories
REFLECTION_LOOKBACK_DAYS	7	Days analyzed in reflection jobs
PATTERN_MIN_FREQUENCY	3	Minimum occurrences to flag as a pattern

---

Project Structure

agentos/
├── server.py              # MCP server entry point
├── daemon.py              # Background daemon entry point
├── config.py              # Settings via pydantic-settings
├── database.py            # SQLite schema and async helpers
│
├── modules/
│   ├── memory/            # Store, retrieve, importance scoring
│   ├── goals/             # CRUD, priority calculation
│   ├── reflection/        # Action logging, pattern detection
│   └── context/           # Unified snapshot builder
│
├── tools/                 # MCP tool definitions (one file per module)
│
└── daemon/
    ├── writer.py          # Shared DB writer for all jobs
    └── jobs/
        ├── memory_decay_job.py
        ├── goal_monitor_job.py
        ├── reflection_analyzer_job.py
        └── self_maintenance_job.py

---

Roadmap

• PostgreSQL support for multi-user deployments
• REST API alongside MCP
• Web dashboard for monitoring agent state
• Plugin system for custom observers and tools
• Multi-agent memory sharing

---

License

MIT — see LICENSE