The first AI plugin that speaks first. Code-enforced learning + active forgetting + PAC (Proactive Accountability Challenge). Works with Claude Code, Gemini CLI, Hermes, OpenClaw.
Quickstart • PAC ๐ช • What Enso Adds • Works With • How It Works • ไธญๆ
Enso is the first AI plugin that speaks first.
Every LLM product today โ ChatGPT, Claude, Gemini, Perplexity โ is built on the same anti-pattern: AI responds, AI never initiates. It observes your mistakes and stays silent. It sees your self-limiting patterns and waits for you to ask.
Enso breaks that silence. It is a discipline plugin that adds three things no mainstream AI product has by default:
- Code-enforced learning โ errors become hooks, not prompts. No third strike.
- Active forgetting โ stale knowledge is pruned. Not all memory is worth keeping.
- ๐ช PAC (Proactive Accountability Challenge) โ AI that raises the issue you haven't asked about.
Quickstart
# Claude Code (default)
git clone https://github.com/amazinglvxw/enso-os.git
cd enso-os && bash install.sh
Gemini CLI
bash install.sh --target gemini-cli
Hermes Agent
bash install.sh --target hermes
OpenClaw
bash install.sh --target openclaw
Any agent with lifecycle hooks
bash install.sh --target genericThat's it. Start a new session. Enso is active:
Session 1: You hit an error -> Enso captures it automatically
Session ends -> Enso distills 1-3 lessons from the error
Session 2: Enso injects the lessons -> Agent avoids the same mistake You didn't do anything. The system learned by itself.
PAC โ Proactive Accountability Challenge (New in v0.7.0)
"PAC is not a judge. It's a mirror."
Every mainstream LLM is query-response. You ask, AI answers. If you don't ask about the blindspot, AI doesn't raise it. This is polite. It is also โ for serious users โ expensive.
PAC adds the missing half: observation-initiated dialogue. Enso watches your session logs, memory files, and decision patterns. When it detects self-limiting behavior that you haven't asked about, it writes a Socratic challenge and delivers it at the start of your next session.
The Five Patterns PAC Detects
| # | Pattern | Example Trigger | |---|---------|-----------------| | 1 | Repetition โ Starting new while old is incomplete | 5 new business lines in 30 days, each lasting 4 days | | 2 | Claim-Action Conflict โ Stated focus โ executed focus | MEMORY says "focus on X", logs show 70% on Y | | 3 | Capability-Task Mismatch โ Strategy delegated to executors | Supply-chain risk handed to an ops person with past failures | | 4 | Sunk Cost โ Long-running zero-growth with tactical churn | 47 days, 17 days zero growth, pricing changed twice, core assumption never questioned | | 5 | Critical Decision Node โ Irreversible action about to ship | "about to sign" on a $50k contract |
Constraint vs Self-Limitation โ The Critical Distinction
A naive challenger burns out the user. PAC's core innovation is classification:
- ๐ข Constraint-optimal (DO NOT challenge) โ User chose X because of real-world limits they can't change (no runway, family obligations, health). Affirm the choice.
- ๐ด Self-limiting (MUST challenge) โ User has the capability and keeps tripping on the same pattern. Challenge firmly.
Quality Standards
Every PAC challenge must pass five checks before it ever reaches you:
| # | Rule | Bad | Good | |---|------|-----|------| | 1 | Based on observation, not wisdom | "You should focus more" | "execution-log shows 9 active lines in 30 days" | | 2 | Point to structure, not instance | "Why did you do X?" | "Why do you always do X-type things?" | | 3 | Challenge premise, not options | "A or B?" | "Why do you need this at all?" | | 4 | Time dimension | "This is wrong" | "In Q1 you did X, Q2 also X โ why?" | | 5 | No answer given | "You should do Y" | "If you only had 3 options, what would they be?" |
Anti-Fatigue by Design
- Max 1 challenge per 24 hours (hard limit)
- Max 3 challenges per week (hard limit)
- 7-day silence period after any challenge on the same pattern
- 1-month cooldown after 3 consecutive user rejections
PAC_ENABLED=falseto disable entirely
Example Output
<enso-pac-challenge c pattern="claimactionconflict">
<observation>
You told me 3 weeks ago to focus on the survival layer.
execution-log shows 60% of your actual actions on the ambition layer
and 25% on the remote layer. Survival layer: 15%.
</observation>
<challenges>
<q id="1">Is the stated priority still true?</q>
<q id="2">If it is, what's the structural force pulling you elsewhere?</q>
<q id="3">If it isn't, why hasn't the stated priority been updated?</q>
</challenges>
<no-answer>These questions are for you to sit with.</no-answer>
</enso-pac-challenge>The Philosophy
้ๅพท็ป: ็ฅไบบ่ ๆบ๏ผ่ช็ฅ่ ๆใ
Knowing others is intelligence. Knowing yourself is enlightenment.>
PAC is the mirror for ่ช็ฅ (self-knowing). Its goal is not to manage you.
It is to help you see yourself clearly. Once a month, PAC should ask a question
that makes you pause, silent for 30 seconds, unable to immediately answer.>
That 30 seconds of silence is where growth begins.
Full spec: docs/PAC_SPEC.md
What Enso Adds
Enso is a plugin, not a platform. It adds discipline to your existing agent without replacing anything.
| What Enso adds | What your host agent handles | |----------------|------------------------------| | Code-enforced error learning | Context management | | Active forgetting (stale decay, LRU) | Multi-model orchestration | | Immutable self-protection (3 hooks) | Platform integrations | | Knowledge quality checks (weekly lint) | Tool execution | | ๐ช PAC โ AI that initiates, not just responds | Query-response dialogue |
| What Enso enforces (blocks violations) | What Enso audits (logs + warns) | |----------------------------------------|---------------------------------| | Self-protection: agent can't modify its own hooks | Write verification: tracks unverified writes | | Safety scan: blocks secrets/injection in memory files | Memory budget: warns when MEMORY.md is too large |
Enso doesn't replace your agent. It makes it more disciplined. Like SELinux for your AI โ invisible when things go right, invaluable when they go wrong. Your agent keeps doing what it does best (context, tools, models). Enso adds the layer it's missing: learning from failure, forgetting what's stale, and protecting its own rules from itself.
Works With
| Capability | Claude Code | Gemini CLI | Hermes | OpenClaw | Generic | |------------|:-----------:|:----------:|:------:|:--------:|:-------:| | Error capture + distillation | โ | โ | โ | โ | โ | | Lesson injection (SessionStart) | โ | โ | โ | โ | โ | | Tool call tracing | โ | โ | โ | โ | โ | | Active forgetting + maintenance | โ | โ | โ | โ | โ | | Self-protection (core-readonly) | โ | โ | โ | โ | โ | | Memory safety scan | โ | โ | โ | โ | โ | | Memory budget guard | โ | โ | โ | โ | โ | | Write verification audit | โ | โ | โ | โ | โ |
Pre-tool-use hooks (self-protection, safety scan, budget guard, write verification) require the framework to support a "before tool execution" lifecycle event. Hermes, OpenClaw, and generic targets get the full learning + forgetting loop but not the guard layer.
Your Agent (Claude Code / Hermes / OpenClaw / Gemini CLI / ...)
โ every tool call passes through
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Enso Discipline Layer โ
โ ๐ Can't skip ๐ง Learns ๐๏ธ Forgets โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโHow It Works
12 hooks, 5 layers. The agent can't skip what code enforces.
| Layer | Hooks | What they do | |-------|-------|-------------| | Immutable | 3 | Write must verify. Can't modify own rules. Session-end audit. | | Learning | 3 | Log every tool call. Capture errors. Distill lessons via LLM. | | Memory | 1 | Inject lessons + knowledge + wisdom into next session. | | Guard | 3 | Memory budget cap. Block secrets/injection. Auto-maintenance. | | ๐ช PAC | 2 | Scan for self-limiting patterns. Inject pending challenges. |
The two loops:
Error loop: Error -> Capture -> Distill -> Store -> Inject -> Avoid (reactive)
PAC loop: Pattern -> Classify -> Challenge -> Silence -> Observe answer (proactive)Forgetting
Most memory systems only grow. Enso actively forgets โ because not forgetting is more dangerous.
| Mechanism | What it does | |-----------|-------------| | Stale decay | Lessons unused >37 days deleted | | LRU eviction | Over 50 lessons, oldest evicted | | MEMORY.md downsink | Completed items archived | | Trace rotation | >14 days deleted (daily cron) | | Recovery safety net | Deleted lesson reappears as error, flagged |
Health Check
enso-lint.sh runs weekly โ like CI for your knowledge base:
| Check | What it finds | |-------|--------------| | Orphans | Lessons never used (hits:0, >7 days) | | Duplicates | >60% keyword overlap between lessons | | Weak lessons | No actionable verb โ not useful | | Budget | MEMORY.md capacity status |
Every distillation auto-rebuilds lessons/INDEX.md for fast routing.
Architecture
~/.enso/
โโโ core/ # Shared modules
โ โโโ env.sh # Paths, ensoparse(), ensofindmemoryfile()
โ โโโ parse-hook-input.py # JSON parser for all hooks
โ โโโ dikw-utils.py # DIKW operations (7 subcommands)
โ โโโ enso-lint.sh # Weekly health check
โ โโโ rebuild-index.py # Auto-rebuild INDEX.md
โ โโโ deleted-lessons-tracker.py # Recovery safety net
โ โโโ pac-analyzer.py # ๐ช 5-pattern self-limiting detection
โ โโโ pac-question-generator.py # ๐ช Socratic challenge generation
โโโ hooks/ # 12 lifecycle hooks
โ โโโ pre-tool-use/ # core-readonly, budget-guard, safety-scan
โ โโโ post-tool-use/ # physical-verification, trace-emission
โ โโโ post-tool-use-failure/ # error-seed-capture
โ โโโ stop/ # audit, distill, maintenance, pac-challenge
โ โโโ session-start/ # load-lessons, pac-pending-check
โโโ dikw/ # DIKW distillation (Info -> Knowledge -> Wisdom)
โโโ pac/ # ๐ช Pending challenges + history + rate state
โโโ traces/ # Tool call logs + lint reports
โโโ lessons/ # active.md + INDEX.mdPhilosophy: "Constraints are the foundation of flexibility"
Like biological evolution: DNA provides immutable constraints (protein folding physics), but within those constraints, life finds infinite creative solutions.
- 3 immutable hooks = the foundation (never changes)
- Everything else = free to evolve
- Active forgetting = prevents calcification
| Source | Key Insight | |--------|-----------| | OpenAI Harness Engineering | Rules in code, not prompts | | Agent Lightning (Microsoft) | Trace/Span + Hook/Emission dual layer | | fireworks-skill-memory | 200 lines of hooks > 800 lines of prompt | | SWE-agent (NeurIPS 2024) | Constrained interfaces reduce errors |
The Survival Experiment
This project's GitHub metrics are its evolutionary fitness signal:
- Stars = survival ("this is useful")
- Forks = reproduction ("I'm building on this")
- Issues = selection pressure ("improve this")
FAQ
Q: What agents does this work with? Five targets out of the box: Claude Code (default, fully tested), Gemini CLI, Hermes Agent, OpenClaw, and a generic target for any agent with lifecycle hooks.
Q: Does Enso compete with Mem0, Hermes memory, or OpenClaw Dreaming? No. Those are memory systems โ they store facts and context. Enso is a discipline system โ it enforces error learning, active forgetting, and self-protection. They are complementary.
Q: Can I use Hermes memory + Enso together? Yes, that's exactly the point. Hermes handles context and skill creation. Enso adds code-enforced error capture, stale decay, and immutable self-protection on top. Same with Claude Code's Auto Memory or OpenClaw's Dreaming.
Q: Where is my data stored? 100% local. ~/.enso/ on your machine. No cloud, no Docker, no database.
Q: What are the prerequisites? bash and python3 (3.6+). Both are pre-installed on macOS and most Linux distros. No pip install, no npm, no Docker.
Q: Do I need to configure anything after install? No. bash install.sh registers all hooks. Next session, it starts learning.
Q: Why not just use my agent's built-in memory? Built-in memory stores facts. Enso adds what's missing: code-enforced error learning, active forgetting with quality checks, and immutable self-protection hooks that the agent cannot bypass.
Q: Is PAC just another nagging notification system? No. PAC has five anti-fatigue layers: max 1/day, max 3/week, 7-day same-topic silence, 1-month cooldown after 3 rejections, and a confidence threshold that defaults to 0.70. Most sessions trigger zero PAC challenges. When one does trigger, it's because five independent checks all agreed.
Q: What if PAC challenges something I already thought through? PAC distinguishes constraint-optimal choices (don't challenge) from self-limiting ones (must challenge). When uncertain, it stays silent. If it ever misfires, you can dismiss and it enters cooldown on that pattern for 30 days.
Q: Does PAC send my data anywhere? No. Everything is local in ~/.enso/pac/. Pattern detection runs in Python on your machine. The Socratic question generator uses your existing LLM adapter chain (claude โ llm โ openai CLI). No telemetry.
Q: How do I disable PAC? export PAC_ENABLED=false in your shell rc. Or delete the two PAC hooks from ~/.claude/settings.json. The rest of Enso keeps working.
Contributing
See CONTRIBUTING.md. Most impactful:
- Bug reports with repro steps
- New hook ideas
- Compatibility testing with other agents
- DIKW pipeline improvements
License
MIT. See LICENSE.
The enso is drawn in a single stroke โ imperfect, incomplete, beautiful.
This system will never be perfect. But it will always be evolving.
