Aigent Os

[](LICENSE) [](https://claude.ai/code) [](https://obsidian.md) [](#-quick-start) [](#-contributing)

The personal operating system that operates itself.

An AI that operates on itself — and a toolbox that manages itself, on top of it.

[Quick Start](#-quick-start) · [Architecture](#-architecture) · [Key Concepts](#-key-concepts) · [Customize](#-make-it-yours) · [Docs](docs/getting-started.md)

---

What if your AI remembered everything?

Every priority. Every decision. Every conversation thread left open from last week. What if it knew exactly what it was allowed to decide on its own — and what to bring to you? What if it could delegate to faster, cheaper agents for grunt work while it stayed focused on strategy?

That's aigent-OS. A 15-document kernel (plus extended specs) that turns Claude Code into a persistent operating system.

No database. No server. No build step. Drop the files in, open a session, and your AI boots up knowing who it is, what it's working on, and what matters today. The system is also recursive — aigent-OS uses its own skills to maintain and publish itself. ([How this repo maintains itself](#-how-this-repo-maintains-itself) · [Manifesto](docs/manifesto.md))

> Dependency model: The core kernel is markdown + shell — no build step, no database, no server. Optional features (semantic search, hooks automation) require Node.js 18+ and are installed automatically by the installer if Node is present. Obsidian is optional for visual vault navigation.

You: /open
aigent: 3 open threads from yesterday. Delegation tracker has 2 items pending review.
       Priority 1 is blocked — surfacing now. What do you want to hit?

---

> v0.7 (2026-05-09): Cognitive architecture shipped — runtime consciousness (ACTIVE_STATE computed on every /open and /close), persistent self-model (capabilities, limitations, failure modes), goal stack with success criteria, belief tracking with confidence scores, operational lessons + procedures, /dream offline consolidation, /reconcile cross-system consistency checks, /meta-improve constrained self-modification, eval harness. aigent-OS now models itself, tracks what it believes, detects drift, and proposes its own improvements. See [The Cognitive Architecture](#-the-cognitive-architecture) below.

> v0.6 (2026-05-08): Self-learning engine — skill recall + taxonomy search, capability expansion, capsule v2, temporal fact ledger, failure-to-artifact pipeline. See [The Self-Learning Engine](#-the-self-learning-engine) below.

> v0.5 (2026-05-03): Somatic layer shipped — body-check reflection, context capsules, agent fitness tracking, system-check audits. See [The Somatic Layer](#the-somatic-layer) below.

---

⚡ Quick Start

Install from your downloaded folder:

You've already downloaded and unzipped aigent-OS. Open a terminal in the unzipped folder and run:

bash install.sh

That's it. aigent-OS installs into whatever directory you're in — your existing project, your home folder, wherever you work. No new directory to switch to.

The installer handles everything automatically: copies the kernel files, creates .claude/settings.json with your actual paths substituted, and installs semantic search if Node.js is available.

> Optional --no-deps: If you want to skip the Node.js semantic-search install, run bash install.sh --no-deps instead.

Start a new Claude Code conversation in the same directory. aigent-OS is live.

Every session works like this:

• Start: /open — aigent-OS boots with full context from last session
• Work: Just talk. aigent-OS handles routing, memory, delegation.
• End: /close — Saves everything. Next session picks up exactly where you left off.

Optional: Open the vault/ folder in Obsidian to see and navigate your AI's knowledge graph visually.

Full setup walkthrough: [Getting Started](docs/getting-started.md) · Advanced config: [Advanced Setup](docs/advanced-setup.md)

---

🗂 Repo Map

system/                            The 15-document operating kernel (00_identity → 15_somatic_layer)
vault/                             Persistent memory and knowledge graph (markdown, Obsidian-native)
vault/agents/                      Instrument roster — 9 named sub-agents (Pantheon Round 4)
skills/                            Claude Code slash-command skills (60+ source templates)
hooks/                             Automation hook scripts (session summary, token tracking, compact nudge)
daemons/                           Background helpers (Caddy, semantic search, memory-heat, runtime state)
daemons/runtime/                   Runtime consciousness daemon (update-active-state.py)
docs/                              Setup guides, doctrine references, architecture roadmaps
memory/                            Ledger templates (SKILL_LEDGER, SKILL_GAPS, SKILL_CHAINS, facts/)
memory/runtime/                    Cognitive layer (ACTIVE_STATE, SELF_MODEL, GOAL_STACK, BELIEF_STATE, LESSONS, PROCEDURES)
memory/runtime/improvements/       Self-improvement archive (candidates, accepted, rejected)
evals/                             Evaluation test definitions (skill-recall, contradiction, capsule-resume)
install.sh                         One-line installer

system/15_somatic_layer.md         Somatic doctrine (body state, lazy compute, organs)
memory/BODY_STATE.json             Current internal-state snapshot
memory/AGENT_FITNESS.md            Per-dispatch fitness ledger
memory/MEMORY_CANDIDATES.md        Staged auto-capture queue
daemons/system-check.sh            Smoke test for skills, daemons, state files
daemons/capsule-compact.py         Chain compaction
daemons/agent-fitness-extract.py   JSONL transcript → fitness classifier
daemons/agent-fitness-report.py    Per-agent calibration report

> Skills path note: skills/ in this repo contains source templates. The installer copies them to .claude/skills/ in your working directory, which is where Claude Code looks for slash commands at runtime. If you add skills manually, place them in .claude/skills//SKILL.md.

---

👀 What a session actually looks like

You: /open

AI:  3 open threads from yesterday.
     - Pricing decision pending (you said you'd think on it overnight)
     - Engineering brief for the auth refactor needs your sign-off
     - Onboarding flow draft ready for your review

     Active priorities:
     1. Close the bridge round (blocked on legal review)
     2. Ship onboarding v2 (in progress, ~70% done)
     3. Hire #5 engineer (interviews scheduled this week)

     Last session you were heads-down on the onboarding flow.
     Want to pick that up, or hit one of the open threads first?

You: pricing first. Going with $49 annual, $59 monthly.

AI:  Locked. I'm writing it to vault/concepts/Pricing Strategy.md and
     logging the decision in DECISION_LOG. Reasoning captured: 17%
     monthly premium is standard SaaS, annual-pre-pay customers
     churn 4× less. Want me to also draft the pricing-page copy
     change for engineering, or is that part of onboarding v2?

You: part of v2.

AI:  Got it. Updating the Onboarding v2 project note. Anything else
     before we move on?

[... 90 minutes of work ...]

You: /close

AI:  Session captured. Summary written to vault/daily/2026-04-25.md.

     What you decided today:
     - Pricing: $49/$59 split. Logged.
     - Onboarding v2: ship Friday, no further scope additions.

     Open threads carrying to next session:
     - Engineering brief still pending sign-off
     - Hire #5 — call back to candidate B by Tuesday

     See you tomorrow.

That's the loop. /open → work → /close. The vault remembers everything. Next session picks up exactly where you left off. See [vault/examples/](vault/examples/) for what populated content actually looks like.

---

🎯 Who this is for

aigent-OS is built for principals running complex parallel work — not for developers building agent pipelines.

• Solo founders juggling product, hiring, fundraising, and ops simultaneously.
• Technical leads managing multiple workstreams across teams.
• Operators in any role where the job is to make decisions, route work, and not lose context.

If you've ever closed your laptop on Friday and opened it Monday wondering what the hell you were in the middle of — that's the problem this solves. The AI remembers so you don't have to.

If you're building an agent framework for end-users to consume, you probably want LangChain or CrewAI instead. aigent-OS optimizes for one principal, many threads, persistent context.

---

🆚 Compared to alternatives

| | aigent-OS | Plain CLAUDE.md | MemGPT / mem0 | LangChain / CrewAI | |---|:---:|:---:|:---:|:---:| | Persistent memory across sessions | ✅ | ❌ | ✅ | depends | | Human-readable knowledge | ✅ Markdown | ✅ Markdown | ❌ embeddings | ❌ embeddings | | Authority / autonomy framework | ✅ | ❌ | ❌ | partial | | Sub-agent routing + delegation | ✅ | ❌ | ❌ | ✅ (different shape) | | No database / server / build step | ✅ | ✅ | ❌ | ❌ | | Built for principals, not developers | ✅ | ❌ | ❌ | ❌ | | Obsidian-native vault | ✅ | ❌ | ❌ | ❌ |

The honest tradeoff: aigent-OS is opinionated. If you want a flexible toolkit you build on, pick LangChain. If you want a memory layer for an existing AI app, pick mem0. If you want your AI to actually run your operating cadence — /open, work, /close, week after week — pick this.

---

🫀 The Somatic Layer

Released 2026-05-03. The somatic layer gives the OS a body — a way to read its own state (context pressure, memory backlog, decision pressure, token usage, attention drift) before acting. Lazy-computed, no daemon. Includes session-resume capsules, agent fitness tracking, and a /system-check reflection organ.

| Skill | When to invoke | What it does | |---|---|---| | /body-check | "how am I doing" / pre-action gut-check | Reads pressure signals across vault, surfaces recommended reflex | | /context-capsule | Context pressure rises OR task completes | Structured state preservation, resume-ready | | /capsule-compact | Manual, on long capsule chains | Walks chain backward, summarizes oldest 3 once depth ≥ 5 | | /digest | Review staged memory candidates | Surfaces each with promote/skip/supersede options | | /agent-fitness | Pre-dispatch agent quality check | Per-agent calibration ratios from JSONL transcripts | | /sweep-now | On-demand vault hygiene | Dispatches Hestia for stale tracker / heat / wikilink sweep | | /system-check | Manual diagnostic | Smoke-tests every wired skill, daemon, state file |

---

🧠 The Self-Learning Engine

Released 2026-05-08. The self-learning engine makes aigent-OS a system that expands its own capability surface. It never stops at inability — it recalls, hunts, workarounds, learns, and captures every failure as a durable artifact. All of this is automatic. The user only types /open and /close.

Core capabilities

| Capability | What it does | How it fires | |---|---|---| | Skill Recall | Searches 64 skills by taxonomy when you describe a task | Caddy auto-fires on every prompt | | Skill Hunt | Searches GitHub and skill marketplaces for missing capabilities | Auto-fires when recall finds no match | | Solution Hunt | Finds 3 alternate routes when blocked (direct fix, workaround, replace) | Caddy fires on "stuck", "blocked", "can't do" | | Learn from Failure | Classifies failures, checks repetition, produces durable artifacts | Caddy fires on "happened again", "same issue" | | Capsule v2 | Resumable execution state with waitingon, successcriteria, next_action | /close creates; /open offers resume | | Temporal Facts | Facts with provenance, validity windows, supersede chains | /close auto-captures new facts | | Skill Gap Scan | Weekly scan for open gaps older than 7 days | /open auto-runs |

How it works

Task arrives → Caddy classifies intent
  → Search skill-index triggers (fast, regex)
  → Search SKILL_LEDGER taxonomy (broader, keyword)
  → Search SKILL_CHAINS for prior successful sequences
  → If all miss: log gap, auto-hunt GitHub

Failure occurs → Classify (routing / verification / tool / knowledge / authority)
  → Check FAILURE_MODES for repetition
  → First time: log and monitor
  → Second time: mandatory artifact (rule, skill, Caddy trigger, checklist)
  → Third time: the artifact itself failed — fix the fix

Key files

| File | Purpose | |---|---| | memory/SKILL_LEDGER.md | Taxonomy-structured index of all installed skills | | memory/SKILL_GAPS.md | Capability gaps discovered during recall | | memory/SKILL_CHAINS.md | Proven multi-skill sequences | | memory/facts/facts.jsonl | Temporal fact ledger with provenance | | docs/capability-expansion-doctrine.md | The expansion loop doctrine | | docs/self-learning-doctrine.md | Failure-to-artifact pipeline | | docs/capsule-v2-doctrine.md | Resumable execution state design | | docs/temporal-fact-ledger.md | Facts with validity windows | | docs/caddy-skill-recall-integration.md | How Caddy does taxonomy search |

Recommended third-party skills

These are not included in aigent-OS but are tested and recommended. Install with /skill-hunt or manually copy to ~/.claude/skills//SKILL.md:

| Skill | Source | License | What it does | |---|---|---|---| | sql-builder | claude-skills-hub | CC BY 4.0 | Natural language to optimized SQL | | query-optimizer | claude-skills-hub | CC BY 4.0 | EXPLAIN plan analysis + index recommendations | | migration-generator | claude-skills-hub | CC BY 4.0 | Zero-downtime database migrations | | git-workflow | freeman983/git-workflow-skill | MIT | Changelog, release, branch strategy | | pdf-workflow | claude-skills-hub | CC BY 4.0 | PDF creation, extraction, merge/split | | data-visualization | claude-skills-hub | CC BY 4.0 | D3/Chart.js chart builder | | api-docs | claude-skills-hub | CC BY 4.0 | OpenAPI 3.0 spec generation | | api-design | setmpp/claude-code-skills | MIT | REST/GraphQL resource modeling |

---

🧬 The Cognitive Architecture

Released 2026-05-09. The cognitive architecture gives aigent-OS a persistent self-model, structured beliefs, goals that survive sessions, and the ability to improve itself through a human-gated dream cycle.

The 4-Level Learning Stack

| Level | What it learns | File | |-------|---------------|------| | 1. Facts | What is true? | memory/facts/facts.jsonl | | 2. Procedures | What works? | memory/runtime/PROCEDURES.jsonl | | 3. Strategies | How to approach problem classes? | memory/runtime/LESSONS.jsonl | | 4. Self-modification | How to improve the improver? | /dream + /meta-improve |

Runtime Consciousness

| File | Purpose | |------|---------| | ACTIVE_STATE.json | Computed live state — mode, objective, pressures, reflexes, blocked items | | SELF_MODEL.json | Capabilities, limitations, recurring failure modes, learning goals | | GOAL_STACK.json | Persistent goals with status, success criteria, blockers, dependencies | | BELIEF_STATE.jsonl | Uncertain assumptions with confidence scores and provenance | | STATE_EVENTS.jsonl | Nervous system event log — every state transition | | LEARNING_SCORECARD.md | Meta-learning metrics — did the learning actually prevent recurrence? |

Autonomous Capabilities (all aigent-OS-internal)

| Skill | What it does | When it fires | |-------|-------------|---------------| | `/reconci

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wrg32786
• Source: wrg32786/aigent-os
• License: MIT
• Homepage: https://theaigent.xyz

Install and usage instructions live in the source repository linked above.