Auto-evolution engine for AI agents — by GravityZenAI.
The agent learns from every interaction, builds a knowledge graph, discovers patterns, creates skills automatically, and evolves its strategies over time. Works with or without LLM — all evolution functions have deterministic fallbacks. Works as an MCP server, CLI tool, or OpenClaw plugin.
- ZERO remote sharing — Nothing leaves your machine. Ever.
- No external API keys — Local SQLite, local embeddings.
- No telemetry — No tracking, analytics, or phone-home.
- Works 100% offline after installation.
- Memory Poisoning Guard — Blocks prompt injection, contradictions, and untrusted memory corruption.
- Zero Trust model — All external input is sanitized before it touches the database.
See SECURITY.md for the full threat model.
| Mode | Command | Use Case |
|---|---|---|
| MCP Server | npx agent-ascend-mcp |
Any MCP-compatible client (Claude, Antigravity, etc.) |
| CLI | npx agent-ascend |
Testing, debugging, manual interaction |
| OpenClaw Plugin | openclaw plugins install ./agent-ascend |
Native OpenClaw integration |
git clone https://github.com/gravityzenai/agent-ascend
cd agent-ascend
npm install
npm run build
npm run mcpAdd to your MCP client config:
{
"mcpServers": {
"agent-ascend": {
"command": "node",
"args": ["dist/src/mcp/server.js"]
}
}
}# Record an experience
agent-ascend remember "Fixed CORS issue in API gateway" --outcome success
# Search past experiences
agent-ascend recall "CORS"
# Get context block for your current task
agent-ascend context "How to fix CORS headers in Express?"
# Check stats and level
agent-ascend stats
agent-ascend level
# Knowledge graph
agent-ascend graph "TypeScript"
# Health check with auto-repair
agent-ascend health
# Export all data
agent-ascend export > backup.json| Tool | Purpose |
|---|---|
ascend_remember |
Record a new experience (task + outcome + feedback + session_id) |
ascend_recall |
Search past experiences with triple hybrid search (FTS5 + semantic + graph) |
ascend_context |
Get a pre-formatted context block for your current prompt — the main way to use memory |
ascend_knowledge |
Search the knowledge base |
ascend_research |
Autonomous research: generates queries for failures, saves search results |
| Tool | Purpose |
|---|---|
ascend_evolve |
Full skill lifecycle via prepare/apply actions (see below) |
ascend_review |
Generate structured review for high-impact experiences |
ascend_errors |
Show error clusters and failure-to-skill candidates |
ascend_chains |
Detect error chains (sequences of co-occurring failures) |
| Tool | Purpose |
|---|---|
ascend_govern |
Approve, reject, freeze, rollback, quarantine, archive skills |
ascend_guard |
Anti-hallucination guard — checks experiences before saving |
ascend_risk_check |
Evaluate promotion risk for patterns/skills |
ascend_integrity |
Memory integrity check and anomaly detection |
| Tool | Purpose |
|---|---|
ascend_session |
Start/end work sessions to group experiences |
ascend_level |
View XP, level, and title |
ascend_stats |
Comprehensive memory statistics and trends |
ascend_strategy |
Strategy learning report with rankings |
ascend_synthesis |
Daily synthesis report with recommendations |
| Tool | Purpose |
|---|---|
ascend_update |
Modify an existing experience |
ascend_forget |
Safely delete experiences (protects high-value, confirms bulk) |
ascend_consolidate |
Merge duplicates, prune expired, boost valuable memories |
ascend_export |
Export skills, stats, and level as JSON |
ascend_import |
Import skills from JSON |
ascend_warmstart |
Bulk import experiences from JSON |
ascend_import_engram |
Import from Engram JSON export |
ascend_graph |
Query the knowledge graph for entity relationships |
ascend_health |
Diagnostics: integrity, FTS sync, auto-repair |
The evolution engine works in two modes:
If a local LLM is configured, evolution runs autonomously — analyzing failures, proposing skills, and evolving strategies.
When no local LLM is available, the host agent (Claude, Antigravity, etc.) drives evolution through the prepare/apply pattern:
1. Agent calls ascend_evolve action="analyze_failures_prepare"
→ Returns failure data + analysis prompt
2. Agent runs the analysis with its own LLM
3. Agent calls ascend_evolve action="analyze_failures_apply"
→ Passes the analysis results back
Available prepare/apply actions:
| Prepare | Apply | Purpose |
|---|---|---|
analyze_failures_prepare |
analyze_failures_apply |
Research failure patterns |
reflect_prepare |
reflect_apply |
Idle reflection on recent experiences |
gepa_prepare |
gepa_apply |
Guided Evolution by Pattern Analysis |
review_prepare |
review_apply |
Structured review of high-impact experiences |
Other evolve actions: propose, activate, deprecate, list, list_needing_evolution, evolve_prepare, evolve_apply
┌──────────────────────────────────────────────────┐
│ AGENT ASCEND v3.2 │
│ │
│ ┌───────────────────────────────────────────┐ │
│ │ 27 MCP Tools (tools.ts) │ │
│ └──────────────┬────────────────────────────┘ │
│ │ │
│ ┌──────────────▼────────────────────────────┐ │
│ │ Evolution Engine (prepare/apply) │ │
│ │ GEPA · PER · Reflection · Synthesis │ │
│ │ Strategies · Error Chains · Risk Check │ │
│ └──────────────┬────────────────────────────┘ │
│ │ │
│ ┌──────────────▼────────────────────────────┐ │
│ │ Governance Layer (v3.0) │ │
│ │ Approve · Freeze · Rollback · Quarantine │ │
│ │ Autonomy Levels · Integrity Monitor │ │
│ └──────────────┬────────────────────────────┘ │
│ │ │
│ ┌──────────────▼────────────────────────────┐ │
│ │ Memory Layer (SQLite) │ │
│ │ ┌─────────┐ ┌───────┐ ┌──────────────┐ │ │
│ │ │ Store │ │ Graph │ │ Knowledge │ │ │
│ │ │ FTS5 │ │ │ │ Manager │ │ │
│ │ └─────────┘ └───────┘ └──────────────┘ │ │
│ │ ┌──────────┐ ┌───────────┐ ┌─────────┐ │ │
│ │ │ Search │ │Consolidate│ │Embeddings│ │ │
│ │ └──────────┘ └───────────┘ └─────────┘ │ │
│ │ ┌──────────┐ │ │
│ │ │ Guard │ ← Memory Poisoning Guard │ │
│ │ └──────────┘ │ │
│ └───────────────────────────────────────────┘ │
│ │
│ 3 Adapters: MCP Server · CLI · OpenClaw Plugin │
│ 3 Modes: zero · economic · full (LLM usage) │
└──────────────────────────────────────────────────┘
See ARCHITECTURE.md for deep dive.
Agent Ascend works in 3 modes depending on LLM availability:
| Modo | LLM calls/día | Comportamiento |
|---|---|---|
| zero | 0 | Todo con fallbacks mecánicos — heurísticas deterministas |
| economic | 50 | Solo evolveSkill + gepaGenerate usan LLM (con gating) |
| full | ilimitado | Todo usa LLM cuando está disponible |
Features:
- LLM Budget Manager — Daily limit tracking con auto-reset
- LLM Cache — Respuestas cacheadas en SQLite (7-day TTL)
- Deterministic fallbacks —
buildFailureHeuristic,chooseBestVariant,mutateSkillDeterministically,evolveSkillWithoutLLM,buildWeeklyReflection
| Level | Title | XP |
|---|---|---|
| 1-10 | 🌱 Novice | 0-999 |
| 11-25 | ⚡ Operative | 1K-6.2K |
| 26-50 | 🛡️ Veteran | 6.7K-25K |
| 51-100 | 🏆 Master | 25K-100K |
| 100+ | 👑 Ascended | 100K+ |
Formula: level = floor(sqrt(xp / 10))
Higher levels unlock more autonomy — at Veteran level, the agent can auto-activate skills. At Master level, it can auto-deprecate and evolve skills.
1. ascend_session action="start" → Get session_id
2. ascend_context prompt="current task" → Get relevant past experiences
3. ... do work ...
4. ascend_remember task="..." session_id=X → Record what happened
5. ascend_session action="end" → Close with summary
- Node.js ≥ 20.0.0
- No external services required
All data stored locally in ~/.agent-ascend/memory.db (SQLite with WAL mode).
Apache 2.0 — © 2026 GravityZenAI