Skip to main content
Glama
Roxmix

AgentOS

by Roxmix
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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

Related MCP server: Consciousness MCP Server

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         │
└─────────────────────────────────────────┘

Quick Setup

Requirements: Python 3.11+

Option 1: Install from PyPI (recommended)

pip install agentos-mcp

That's it. Then create your .env and start both processes:

cp .env.example .env   # if running from source
agentos-server         # Terminal 1 — MCP server
agentos-daemon         # Terminal 2 — background daemon (optional)

Option 2: Install from source

git clone https://github.com/Roxmix/agentos-mcp.git
cd agentos-mcp

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

pip install -e .

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)
agentos-server
# or: python server.py

# Terminal 2 — Background Daemon (runs continuously)
agentos-daemon
# or: 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": "agentos-server"
    }
  }
}

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

Claude Code

claude mcp add-json agentos '{
  "command": "agentos-server"
}'

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 |
|----------|---------|-------------|
| `AGENTOS_DB_PATH` | `~/.agentos/agentos.db` | SQLite database path (set to use a custom location) |
| `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 |
| `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |

**Note:** The database is stored at `~/.agentos/agentos.db` by default. This ensures the MCP server and daemon share the same database whether installed via pip or run from source. Set `AGENTOS_DB_PATH` to use a custom location.

---

## Project Structure

agentos-mcp/ ├── 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_pkg/ # Background daemon package │ ├── 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 │ ├── tests/ # Test suite ├── pyproject.toml # Package metadata & dependencies ├── .env.example # Configuration template └── .github/workflows/ # CI/CD (GitHub Actions)


---

## 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](LICENSE)

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Roxmix/agentos-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server