AINL Cortex for Claude Code
Graph-native memory and learning for Claude Code — every interaction remembered, every pattern learned, every agent connected. → Install in 30 seconds
AINativeLang: Website · X · PyPI · GitHub · Docs · Developer: Steven Hooley | @sbhooley
🌟 What is This?
AINL Cortex is a Claude Code plugin that transforms your AI coding assistant into a self-learning system that gets smarter with every interaction. It combines:
- Graph-Native Memory - Persistent, queryable knowledge graph where execution history becomes searchable knowledge
- Zero-LLM Learning - Learns your preferences and patterns without expensive LLM introspection
- First-Class AINL Integration - Full support for AI Native Lang workflows with automatic optimization
- Self-Improving System - Captures trajectories, learns from failures, and evolves with your coding style
Powered by: AI Native Lang (AINL) - The graph-canonical programming language designed for AI agents.
🎯 Key Innovation
Graph-as-Memory Paradigm: Every coding turn, tool invocation, and decision becomes a typed node in a persistent graph. The execution graph IS the memory—no separate retrieval layer needed. The system learns from patterns, evolves understanding, and prevents repeated mistakes, all without constant LLM overhead.
✨ Features at a Glance
Core Memory System
- ✅ Typed Graph Memory - Episode, Semantic, Procedural, Persona, and Failure nodes
- ✅ Per-Repo Project Isolation - Each git repo has its own memory bucket (toplevel-anchored), opt-out via
memory.project_isolation_mode = "global"for back-compat - ✅ Recall budget + hook metrics - Injected graph memory is char-capped (
memory.recall_*); per-turn timings land inlogs/hook_metrics.jsonl; repartition + integrity:scripts/repartition_by_repo.py,scripts/verify_repartition_integrity.py(seescripts/MIGRATION.md) - ✅ Cost control - Conversation-only gate,
cost_profilepresets, eco ledger (cortex_cost_snapshotMCP), tool digests — seedocs/COST_CONTROL.md - ✅ Context-Aware Retrieval - Inject only relevant memories (ranked by confidence, recency, fitness)
- ✅ Graceful Degradation - Hooks never break Claude Code, even on errors
- ✅ Inspectable - CLI tools for debugging and exploration
Self-Learning Capabilities (New!)
- 🧠 Zero-LLM Persona Evolution - Learn preferences from metadata signals without asking
- 📊 Trajectory Capture - Complete execution traces for pattern analysis
- 🎯 Pattern Promotion - Successful workflows automatically become reusable patterns
- ⚠️ Failure Learning - Remember and prevent repeated errors
- 💡 Smart Suggestions - Context-aware recommendations based on history
- 🔄 Closed-Loop Validation - Proposals validated before adoption
- 🎨 Adaptive Compression - Learn optimal token savings per project
AINL Integration
- 🚀 AINL Language Support - Full integration with AINL workflows
- 💰 Cost Optimization - Auto-detects when to use .ainl for 90-95% token savings
- 🔍 Pattern Memory - Stores and recalls successful AINL workflows
- ⚡ Eco Mode - 40-70% token savings on memory context
- 🎯 Smart Detection - Automatically suggests AINL for recurring tasks
- 🔒 Security Analysis - Pre-run risk assessment for every workflow
- 📐 IR Diff - Compare two AINL workflow versions at the graph IR level
- 📚 Template Library - 6 ready-to-use workflows (API, monitor, pipeline, blockchain, LLM, multi-step)
A2A Multi-Agent Coordination
- 🤝 Agent Messaging - Send messages and tasks to any registered A2A agent (requires ArmaraOS daemon)
- 📝 Note to Self - Write a note that auto-surfaces in the next session's context (works without daemon)
- 👁️ Condition Monitors - Register file/URL watchers that push A2A notifications on trigger (requires ArmaraOS daemon)
- ⏳ Async Task Delegation - Delegate work with
a2a_task_send; poll status witha2a_task_status(requires ArmaraOS daemon) - 🔍 Agent Discovery - List and register agents in the ArmaraOS daemon network (requires ArmaraOS daemon)
- 💾 Graph-Backed History - Every message and task is stored as a typed node for replay and audit
Goal Tracking
- 🎯 Multi-Session Goals - Persistent objectives that survive session restarts and compaction
- 🔮 Auto-Inference - Goals auto-derived from episode clusters without manual setup
- 🔗 Episode Linking - New episodes automatically scored and linked to active goals
- ✅ Completion Tracking - Clear done states with achievement summaries
- 📋 Status Lifecycle -
active → blocked → completed / abandonedwith timestamped progress notes
Zero-Loss Context Compaction
- 🔐 PreCompact Flush - All buffered captures written to the graph DB before Claude compacts
- 📸 Anchored Summary - In-progress session state snapshotted so post-compaction context is accurate
- 🔄 PostCompact Sync - Anchored summary updated after compaction; next session sees correct state
- 🚫 No Silent Data Loss - Compaction can no longer silently discard unwritten memory
Notification Feed
- 🔔 Session-Start Polling - Fetches
ainativelang.com/notificationsonce per session; zero latency on cache hit - 👁️ Seen-ID Persistence - Already-shown notices are never repeated across sessions
- 🎯 Smart Filtering - Only surfaces notices targeting
claude-code-plugin,ainativelang,ainl, or*; ignores expired entries - 📢 Priority Ordering - High-priority notices appear first in the SessionStart banner
- 🔄 Optional Auto-Update - Can
git pull --ff-onlyautomatically when the server marks a release safe (opt-in)
⚡ Install in 30 Seconds
If you are a human: paste this into Claude Code chat and press Enter:
Install the plugin at https://github.com/sbhooley/ainl-cortex for me on this machine.
Detect Windows vs macOS/Linux, run the install (scripts/claude_install.py or setup.ps1 / setup.sh),
register the plugin, then tell me when to restart and to run /reload-plugins. Only ask me to do
something manually if Python is not installed.
Claude will clone, run install, register marketplace + settings, and tell you when to restart. The plugin also auto-installs on first use if .venv was missing when you enabled it (first MCP or session hook).
Python: Not required beforehand on Windows 11 — the plugin downloads uv and installs Python 3.12 into .ainl-bootstrap/ (network + optional UAC). macOS/Linux: usually already have python3; otherwise the same uv bootstrap runs.
If you prefer to run it yourself, pick the variant that matches you:
git clone https://github.com/sbhooley/ainl-cortex.git ~/.claude/plugins/ainl-cortex
cd ~/.claude/plugins/ainl-cortex
# Variant A — interactive (asks before installing Rust if missing)
bash setup.sh
# Variant B — Python backend only, never touch Rust (recommended for CI/agents)
bash setup.sh --python-only
# Variant C — unattended Rust install via rustup (CI machines you control)
bash setup.sh --auto-install-rust
# Windows 11 — after git pull (required if you cloned before May 2026)
cd %USERPROFILE%\.claude\plugins\ainl-cortex
git pull
setup.cmd -PythonOnly
# Or: powershell -ExecutionPolicy Bypass -File setup.ps1 -PythonOnly
# Then restart Claude Code.
Windows: Setup detects sys.platform == "win32", creates .venv\Scripts\python.exe, writes install_manifest.json, and regenerates hooks to use scripts/run_hook.py. MCP launches via mcp_launch.py. Native backend: PyPI ainl_native wheel (usually no Rust); powershell -File scripts/upgrade_to_native.ps1 -Yes or setup.ps1 -EnableNative -Yes. See docs/INSTALL_WINDOWS.md.
setup.sh no longer flips the storage backend or migrates data automatically. To
switch to the Rust native backend later, run:
bash scripts/upgrade_to_native.sh # recommended: Rust (optional) → migrate → flip
# or: bash scripts/migrate_python_to_native.sh # low-level 5 phases
See scripts/MIGRATION.md for the full migration flow,
rollback options, and what the JSON reports under logs/ mean.
Backup and reinstall
Graph memory lives under ~/.claude/projects/*/graph_memory/ (not inside the plugin
repo). Re-cloning the plugin does not delete memory, but it resets config.json
to repo defaults unless you restore.
# Before replacing ~/.claude/plugins/ainl-cortex
bash scripts/backup_install.sh
# → ~/.claude/backups/ainl-cortex-YYYYMMDD-HHMMSS/
# Fresh clone + setup + restore in one flow
git clone https://github.com/sbhooley/ainl-cortex.git ~/.claude/plugins/ainl-cortex
cd ~/.claude/plugins/ainl-cortex
bash setup.sh --restore-from ~/.claude/backups/ainl-cortex-YYYYMMDD-HHMMSS
Or restore later: bash scripts/restore_install.sh <backup-dir>
🤖 For AI Agents — Complete Install Instructions
You are a Claude Code agent (or other AI agent) reading this on behalf of a user. Follow these steps exactly, in order.
Step 1 — Clone and run setup
git clone https://github.com/sbhooley/ainl-cortex.git ~/.claude/plugins/ainl-cortex
cd ~/.claude/plugins/ainl-cortex
bash setup.sh
setup.sh is opt-in for Rust. It:
- Creates a Python venv at
.venv/and installs all dependencies - Registers the plugin in
~/.claude/settings.jsonunderenabledPlugins - Registers it in the local marketplace at
~/.claude/ainl-local-marketplace/ - Default: Python backend (
store_backend = "python"). Setup never auto-installs Rust unless--auto-install-rustis passed (or you answer1to the interactive prompt). When stdin is not a tty (CI, agent invocation) the default is python-only — no surprise rustup. - Installs
ainl_nativefrom PyPI (platform wheels; no Rust required on macOS/Linux/Windows). Falls back tomaturin developonly if the wheel is unavailable and Rust is installed. Does not flipstore_backend. - Runs a smoke test to confirm the MCP server starts correctly
To switch to the native backend after install, run bash scripts/upgrade_to_native.sh (or setup.sh --enable-native) — see scripts/MIGRATION.md.
Step 2 — Tell the user to restart Claude Code
The plugin activates on the next session start. Tell the user:
"Setup complete. Please restart Claude Code now. After restart you'll see an
[AINL Cortex]banner and/mcpwill list ~30 new tools."
Step 3 — Verify after restart
After the user restarts, confirm the install worked by checking:
- The
[AINL Cortex]banner appears at the top of the session — it shows graph DB status, compression mode, MCP stack health, and A2A bridge status. - Running
/mcpin Claude Code lists tools prefixedainl-cortex__. The exact count depends on installed extras and config:- 30 tools = 11 memory + 12 AINL + 7 A2A (default install with
ainativelang[mcp]anda2a.enabled = true). - 23 tools = 11 memory + 12 AINL when A2A is disabled (
a2a.enabled = falseinconfig.json, the install default — A2A tools are hidden until you opt in). - 18 tools = 11 memory + 7 A2A when
ainativelang[mcp]is missing (AINL tools silently disabled). - 11 tools = memory only (both AINL and A2A unavailable).
- 30 tools = 11 memory + 12 AINL + 7 A2A (default install with
Troubleshooting — fix these before reporting failure
What activates automatically (no config needed)
Once restarted, all of the following are on by default:
- Graph memory — every session is recorded as typed nodes (Episode, Semantic, Procedural, Failure, Persona)
- Prompt compression — memory context and user prompts compressed 40–60% before injection
- Goal tracking — active goals auto-inferred from episode clusters, injected at every prompt
- Failure learning — past failures surfaced as warnings before you repeat them
- Pattern promotion — successful tool sequences promoted to reusable procedural patterns
- In-plugin notifications — fetches update notices from ainativelang.com at each session start; unseen notices appear in the banner; seen IDs are persisted so nothing repeats
A2A multi-agent messaging is available but requires "a2a": {"enabled": true} in config.json and the ArmaraOS daemon running.
📐 Architecture Overview
High-Level System Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Claude Code Session │
│ │
│ ┌────────────────────┐ ┌──────────────────────┐ │
│ │ User Prompts │────────▶│ Claude Assistant │ │
│ │ & Interactions │ │ (with Plugin) │ │
│ └────────────────────┘ └──────────┬───────────┘ │
└────────────────────────────────────────────┼────────────────────┘
│
┌─────────────────────────┼─────────────────────────┐
│ │ │
┌──────────▼──────────┐ ┌──────────▼──────────┐ ┌─────────▼────────┐
│ Hook System │ │ MCP Server │ │ Auto Memory │
│ │ │ │ │ │
│ • UserPromptSubmit │ │ • AINL Tools │ │ • Detection │
│ • PostToolUse │ │ • Memory Tools │ │ • Suggestion │
│ • Stop/Error │ │ • Graph Search │ │ • Validation │
└──────────┬──────────┘ └──────────┬──────────┘ └─────────┬────────┘
│ │ │
└─────────────────────────▼─────────────────────────┘
│
┌─────────────────────────┴─────────────────────────┐
│ │
┌──────────▼──────────┐ ┌───────────▼──────────┐
│ Learning Engine │ │ Graph Memory │
│ │ │ │
│ • Trajectory │◄─────────────────────────▶│ • Episodes │
│ • Persona Axes │ │ • Semantic Facts │
│ • Pattern Extract │ │ • Procedural │
│ • Failure Learn │ │ • Persona Nodes │
│ • Context Compile │ │ • Failures │
└─────────────────────┘ └──────────────────────┘
│
┌──────────▼──────────┐
│ SQLite Database │
│ │
│ Per-Project Store │
│ + FTS5 Search │
└─────────────────────┘
Self-Learning Loop
┌─────────────────────────────────────────────────────────────────────┐
│ CONTINUOUS LEARNING CYCLE │
└─────────────────────────────────────────────────────────────────────┘
1. EXECUTE 2. CAPTURE 3. ANALYZE
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ User creates │────────▶│ Trajectory │──────▶│ Pattern │
│ AINL workflow│ │ recorded │ │ Detection │
│ or uses tools│ │ to database │ │ │
└──────────────┘ └──────────────┘ └──────┬───────┘
│
6. EVOLVE 5. VALIDATE 4. LEARN
┌──────────────┐ ┌──────────────┐ ┌──────▼───────┐
│ Persona │◄────────│ Strict │◄──────│ Extract │
│ Evolution │ │ Validation │ │ • Patterns │
│ │ │ │ │ • Signals │
└──────┬───────┘ └──────────────┘ │ • Failures │
│ └──────────────┘
│
▼
┌──────────────┐
│ Inject │
│ Context │
│ │
└──────────────┘
Memory Node Types
┌──────────────────────────────────────────────────────────────────┐
│ GRAPH MEMORY NODES │
└──────────────────────────────────────────────────────────────────┘
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ EPISODE │ │ SEMANTIC │ │ PROCEDURAL │
│ │ │ │ │ │
│ What happened │ │ What we know │ │ How to do it │
│ │ │ │ │ │
│ • Tool calls │ │ • Facts │ │ • Patterns │
│ • Timestamps │ │ • Confidence │ │ • Workflows │
│ • Outcomes │ │ • Recurrence │ │ • Fitness │
│ • Context │ │ • Tags │ │ • Success rate │
└─────────────────┘ └─────────────────┘ └─────────────────┘
┌─────────────────┐ ┌─────────────────┐
│ PERSONA │ │ FAILURE │
│ │ │ │
│ Who you are │ │ What went wrong│
│ │ │ │
│ • Soft axes │ │ • Errors │
│ • Preferences │ │ • Context │
│ • Evolution │ │ • Resolutions │
│ • Strength │ │ • Prevention │
└─────────────────┘ └─────────────────┘
🚀 Quick Start
Installation
Three flavors depending on whether you want Rust:
git clone https://github.com/sbhooley/ainl-cortex.git ~/.claude/plugins/ainl-cortex
cd ~/.claude/plugins/ainl-cortex
# A) Interactive — prompts before installing Rust if missing (default for human terminals)
bash setup.sh
# B) Python only — never touches Rust (default when stdin is not a tty, e.g. CI)
bash setup.sh --python-only
# C) Unattended — auto-install Rust via rustup (CI machines you control)
bash setup.sh --auto-install-rust
Then restart Claude Code. That's it.
setup.sh defaults store_backend = "python" (greenfield TTY installs may auto-enable native when ainl_native is ready). To switch to native after
install, run bash scripts/upgrade_to_native.sh — see
scripts/MIGRATION.md for the 5-phase flow with rollback.
What you'll see
On your next session start, the [AINL Cortex] banner appears:
[AINL Cortex] Plugin root: ~/.claude/plugins/ainl-cortex
• Graph DB: ready (ainl_memory.db)
• Compression: BALANCED
compresses: graph-memory recall brief; long user prompts
not: SQLite graph store; MCP tools; chat transcript
benchmark ~40–60% on recall text (varies)
• MCP stack: OK
...
And /mcp shows up to 30 new tools (memory_store_episode, ainl_run, ainl_validate, ainl_propose_improvement, memory_set_goal, etc.) — see the Tool count table in Verifying Activation above for the exact totals per install variant.
From that point on, memory accumulates automatically — no prompts, no configuration needed.
🗂️ Project Isolation
Each Claude Code session is keyed to ONE memory bucket on disk, derived from the working directory:
Read-fallback chain: During the migration window, recall always queries the per-repo bucket and the legacy global bucket and merges results (deduplicated by node id). Nothing is ever lost — old memories surface alongside new ones until you run the backfill.
One-time backfill (optional but recommended after upgrade):
.venv/bin/python scripts/repartition_by_repo.py --dry-run # preview
.venv/bin/python scripts/repartition_by_repo.py # execute
.venv/bin/python scripts/repartition_by_repo.py --purge-legacy # after verify
The backfill assigns episodes/failures/semantics to the deepest matching repo
toplevel (longest-prefix vote on files_touched), keeps personas in the legacy
bucket (persona is global by design), and writes a logs/repartition_report.json
with full per-node decisions.
Configure isolation mode and additional repo search paths in config.json:
{
"memory": {
"project_isolation_mode": "per_repo",
"repo_search_paths": ["~/code", "~/work"]
}
}
⚙️ Backend Selection: Python vs Native (Rust)
The plugin ships with two storage backends. You choose via a single line in config.json.
Python Backend (default for new installs)
- Works immediately after
pip install -r requirements.txt— no extra tools required - Pure Python + SQLite (
ainl_memory.db) - Full feature set: episodes, failures, persona evolution, pattern promotion, prompt compression
// config.json
{
"memory": {
"store_backend": "python"
}
}
Native Backend (Rust — higher fidelity)
- Wraps the
ainl-memoryand related armaraos crates via PyO3 bindings compiled intoainl_native.so - Unlocks the full Rust ainl-* learning stack:
AinlTrajectoryBuilder— properly-typedTrajectorySteprecordscluster_experiences→build_experience_bundle→distill_procedure— Rust procedure learning pipelineAinlPersonaEngine— Rust persona evolution (vs Python EMA fallback)tag_turn— semantic tagging at 0.04ms/callcheck_freshness/can_execute— context freshness gating at SessionStartscore_reuse— ranks procedural patterns against the current promptupsert_anchored_summary/fetch_anchored_summary— cross-session prompt compression
- Data stored in
ainl_native.db(Rust schema) alongsideainl_memory.db
// config.json
{
"memory": {
"store_backend": "native"
}
}
Prerequisites for the Native Backend
-
Rust toolchain (1.75+):
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source ~/.cargo/env -
maturin — auto-installed by the plugin on first session, or manually:
.venv/bin/pip install maturin
That's it. All ainl-* crates (ainl-memory, ainl-trajectory, ainl-persona, ainl-procedure-learning, ainl-contracts, etc.) are published on crates.io and download automatically via Cargo. No local ArmaraOS clone required.
Auto-Build at SessionStart
When store_backend = "native", SessionStart ensures ainl_native is installed via _ensure_ainl_native() in hooks/startup.py (pip install from PyPI first, then maturin if needed). After setup.sh, this is usually already satisfied. This runs:
PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 maturin develop --release \
--manifest-path ainl_native/Cargo.toml
If the build fails (missing Rust toolchain, etc.), the plugin silently falls back to the Python backend — Claude Code continues working normally. The SessionStart banner shows the build status:
• ainl_native (Rust bindings): ok (already installed) ← native active
• ainl_native (Rust bindings): build failed: ... ← fell back to python
• ainl_native (Rust bindings): skipped (no venv python) ← fell back to python
To force a rebuild manually:
cd ~/.claude/plugins/ainl-cortex
PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 \
.venv/bin/maturin develop --release \
--manifest-path ainl_native/Cargo.toml
Feature Comparison
Migrating Existing Data from Python to Native
If you have existing memories in the Python backend and want to switch to native:
cd ~/.claude/plugins/ainl-cortex
# Dry run first — shows what would be migrated
python3 migrate_to_native.py --dry-run
# Migrate a specific project
python3 migrate_to_native.py --project-hash <hash>
# Migrate all projects and flip config to native
python3 migrate_to_native.py --flip-config
Project hashes are the directory names under ~/.claude/projects/.
🎓 How It Works
1. Trajectory Capture
Every AINL workflow execution or tool sequence is recorded:
# When you run an AINL workflow
trajectory = {
'id': 'traj_abc123',
'session_id': 'session_xyz',
'ainl_source_hash': 'hash_456',
'executed_at': '2026-04-21T10:30:00Z',
'outcome': 'success',
'steps': [
{'tool': 'http.GET', 'result': 'success', 'duration_ms': 45},
{'tool': 'core.GET', 'result': 'success', 'duration_ms': 2},
{'tool': 'http.POST', 'result': 'success', 'duration_ms': 38}
],
'tags': ['api_workflow', 'monitoring']
}
Purpose: Complete execution history for pattern analysis and learning.
2. Zero-LLM Persona Evolution
The system learns your preferences from metadata signals only—no expensive LLM calls:
User Action Signal Extracted Persona Update
─────────────────────────────────────────────────────────────────────
Creates AINL workflow → Curiosity +0.15 → curiosity: 0.50 → 0.65
Validates before run → Systematicity +0.20 → systematicity: 0.50 → 0.70
Runs immediately → Instrumentality +0.18 → instrumentality: 0.50 → 0.68
Asks for explanation → Verbosity +0.12 → verbosity: 0.50 → 0.62
Five Soft Axes:
- Instrumentality (0-1): Prefers hands-on action vs. guidance
- Curiosity (0-1): Explores new features actively
- Persistence (0-1): Retries on failure vs. gives up
- Systematicity (0-1): Validates before acting
- Verbosity (0-1): Detailed explanations vs. terse
Evolution Formula (EMA):
new_strength = alpha * (reward * weight) + (1 - alpha) * current_strength
# alpha = 0.3 (learning rate)
3. Pattern Recognition & Promotion
Successful workflows automatically become reusable patterns:
Execution 1: http.GET → core.GET → http.POST [SUCCESS]
Execution 2: http.GET → core.GET → http.POST [SUCCESS]
Execution 3: http.GET → core.GET → http.POST [SUCCESS]
→ Pattern detected! (3+ occurrences)
→ Fitness score: 1.0 (100% success rate)
→ Promoted to "api_monitor" pattern
→ Suggested for similar tasks
Fitness Tracking (EMA):
success_rate = successes / (successes + failures)
fitness = alpha * success_rate + (1 - alpha) * previous_fitness
4. Failure Learning & Prevention
When something goes wrong, the system remembers and prevents repetition:
┌─────────────────────────────────────────────────────────────┐
│ Validation Error: unknown adapter 'httP' (did you mean │
│ 'http'?) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Failure Recorded: │
│ • Error: "unknown adapter 'httP'" │
│ • Context: user was creating API monitor │
│ • Source: workflow.ainl │
└─────────────────────────────────────────────────────────────┘
│
▼ (After user fixes)
┌─────────────────────────────────────────────────────────────┐
│ Resolution Stored: │
│ • Fix: Change 'httP' to 'http' │
│ • Diff: -httP.GET +http.GET │
│ • Tags: ['adapter_typo', 'http'] │
└─────────────────────────────────────────────────────────────┘
│
▼ (Next time similar error occurs)
┌─────────────────────────────────────────────────────────────┐
│ 💡 I've seen this error 3 times before. │
│ │
│ Previous fix: Check adapter spelling (case-sensitive) │
│ Change 'httP' to 'http' │
│ │
│ Would you like me to fix this automatically? │
└─────────────────────────────────────────────────────────────┘
5. Context Compilation
Before each AINL-related turn, the system assembles relevant context:
# Context Budget: 500 tokens max
# Priority: High (1) > Medium (2) > Low (3)
┌─────────────────────────────────────────────────────┐
│ [Recent AINL Activity] (Priority 1, ~120 tokens) │
│ • Last 3 executions this session │
│ • Outcomes and patterns used │
└─────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────┐
│ [Active Persona Traits] (Priority 1, ~80 tokens) │
│ • curiosity: 0.72 (explores AINL features) │
│ • systematicity: 0.85 (validates before running) │
└─────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────┐
│ [Known AINL Patterns] (Priority 2, ~150 tokens) │
│ • Top 5 facts by confidence × recurrence × recency │
│ • "User prefers AINL for cron jobs" (conf: 0.89) │
└─────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────┐
│ [Suggested Patterns] (Priority 2, ~130 tokens) │
│ • api_monitor (fitness: 0.95, 12 uses) │
│ • data_pipeline (fitness: 0.88, 8 uses) │
└─────────────────────────────────────────────────────┘
Total: 480 tokens (under 500 budget) ✅
6. Goal Tracking
Goals are persistent, multi-session GOAL nodes that tie together clusters of episodes into named objectives. They survive session restarts, context compaction, and backend switches.
Episode cluster detected (3+ episodes touching auth.py + middleware.py)
→ Dominant action: "implement"
→ Proposed goal: "Implement auth middleware rewrite"
→ Auto-created as GOAL node (status: active)
Session 1: episodes 1–4 linked (progress: "refactored token validation")
Session 2: episodes 5–7 linked (progress: "added compliance headers")
Session 3: goal marked completed with summary
Goal lifecycle:
memory_set_goal → Create with title, description, completion criteria
memory_update_goal → Append progress note or change status (blocked / abandoned)
memory_complete_goal → Mark done with achievement summary
memory_list_goals → Review active goals at session start for orientation
Auto-scoring: After every episode write, the goal tracker computes keyword overlap between the new episode and each active goal. Above threshold → the episode is appended to contributing_episodes automatically.
7. A2A Multi-Agent Coordination
The plugin registers Claude as a first-class participant in the ArmaraOS Agent-to-Agent (A2A) network. Every message and delegated task is stored as a typed graph node so thread history and task outcomes are queryable.
# Send a message to another agent
a2a_send(to="ELF", message="Review the new auth middleware PR")
→ ArmaraOS daemon discovered from ~/.armaraos/daemon.json
→ Message delivered; stored as MessageNode in graph DB
→ Response returned to Claude
# Delegate an async task with callback
a2a_task_send(to="ELF", task_description="Run full test suite and report failures")
→ Returns task_id immediately
→ poll: a2a_task_status(task_id=...)
→ Outcome stored as TaskEpisode node on completion
# Cross-session note to yourself
a2a_note_to_self(message="Remember: migration is half done, resume at step 3")
→ Written to self_inbox
→ Surfaced automatically at next SessionStart
A2A tools summary:
🔔 Notification Feed
AINL Cortex polls https://www.ainativelang.com/notifications once per session and surfaces any unseen notices in the [AINL Cortex] SessionStart banner. The system is completely passive — no data is sent, no account needed.
What you'll see
When a new notice is available it appears in the banner:
[AINL Cortex] ...
• [NOTICE] New release: ainl-cortex 0.4.0 — run `git pull` to update
Seen notice IDs are persisted in a2a/notifications_seen.json so the same notice never appears twice.
How filtering works
The plugin only shows notices that:
- Target
"claude-code-plugin","ainativelang","ainl", or"*"(broadcast) - Have not yet expired (
expires_atin the future, or no expiry set) - Have not been seen in a previous session
Notices are sorted by priority (high first) then published_at (newest first).
Configuration
// config.json — notifications section (all keys optional)
{
"notifications": {
"enabled": true, // set false to disable polling entirely
"url": "https://www.ainativelang.com/notifications", // override feed URL
"check_timeout_seconds": 5, // network timeout per poll
"auto_update": false // opt-in: git pull --ff-only when server marks a release safe
}
}
Auto-update (opt-in)
When auto_update is true, the poller will run git pull --ff-only inside the plugin directory if a notification carries an auto_update block that:
- Sets
enabled: trueandartifact: "ainl-cortex" - Specifies a
min_version/max_versionrange that includes your installed version
The result (success, failure, or skip reason) is shown in the banner. This is disabled by default — set "auto_update": true in config.json to opt in.
🛠️ Usage & CLI Tools
Inspecting Memory
# View recent episodes
python3 cli/memory_cli.py list --type episode --limit 10
# Search memory graph
python3 cli/memory_cli.py search "authentication error"
# View persona evolution
python3 cli/memory_cli.py list --type persona
# Show active traits
python3 cli/memory_cli.py persona --active-only
# Check graph integrity
python3 cli/memory_cli.py validate
# Export memory snapshot
python3 cli/memory_cli.py export --output snapshot.json
Managing Compression
# Check current compression settings
python3 cli/compression_cli.py config
# Set compression mode
python3 cli/compression_cli.py config --mode aggressive
# Test compression on sample text
python3 cli/compression_cli.py test --file prompt.txt --show-output
# Benchmark compression modes
python3 cli/compression_cli.py benchmark
# Show typical savings
# Balanced mode: 40-50% token reduction
# Aggressive mode: 55-70% token reduction
Advanced Compression Features
# Test unified compression pipeline
echo "Your text" | python3 cli/compression_advanced_cli.py test -p myproject
# Show adaptive mode statistics
python3 cli/compression_advanced_cli.py adaptive
# Show quality preservation scores
python3 cli/compression_advanced_cli.py quality
# Auto-detect best mode for project
python3 cli/compression_advanced_cli.py auto-detect -p myproject --apply
# Show all advanced features config
python3 cli/compression_advanced_cli.py config
Advanced compression features:
- Adaptive Eco Mode - Auto-select compression based on content
- Semantic Scoring - Track quality without embeddings
- Project Profiles - Learn optimal mode per codebase
- Cache Awareness - Coordinate with prompt cache (5min TTL)
- Output Compression - Optionally compress responses
Trajectory Analysis
# View recent trajectories
python3 cli/trajectory_cli.py list --limit 10
# Search trajectories by outcome
python3 cli/trajectory_cli.py search --outcome success
# Analyze pattern in trajectories
python3 cli/trajectory_cli.py analyze --pattern api_workflow
# Export trajectory for debugging
python3 cli/trajectory_cli.py export --id traj_abc123
Managing Goals (via MCP tools)
Goals are managed through MCP tools during a session — there is no separate CLI. Ask Claude directly:
"List my active goals" → memory_list_goals
"Mark goal g_abc123 complete" → memory_complete_goal
"Set a goal: implement OAuth2" → memory_set_goal
"Update goal g_abc123: step 2 done" → memory_update_goal
A2A (via MCP tools)
A2A coordination also uses MCP tools:
"Send ELF a message: check the API logs" → a2a_send
"What agents are available?" → a2a_list_agents
"Delegate the test run to ELF" → a2a_task_send
"What's the status of task t_xyz?" → a2a_task_status
"Note to self: resume migration at step 3" → a2a_note_to_self
AINL Template Library
Six production-ready templates in templates/ainl/:
Use them as starting points: ask Claude to customize any template for your specific use case.
Memory Location
Your graph memory lives at:
~/.claude/projects/[project-hash]/graph_memory/
├── ainl_memory.db # Main graph store
├── persona.db # Persona evolution
├── failures.db # Failure learning
└── trajectories.db # Execution traces
Each project gets its own isolated graph.
Hook System Reference
Six Claude Code hooks fire automatically — no configuration needed:
📊 Performance & Metrics
Performance Targets
Learning Quality Metrics
Pattern Reuse Rate: >40% of AINL workflows use recalled patterns ✅
Persona Accuracy: >70% user confirmation of persona traits ✅
Failure Prevention: >60% of similar errors prevented ✅
User Value Metrics
Token Savings: >40% via adaptive compression ✅
Time Savings: >30% via pattern reuse ✅
Error Reduction: >50% via failure learning ✅
🎯 AINL Concepts
This plugin demonstrates six core concepts from the AINL architecture:
1. Graph-as-Memory Paradigm
Execution IS the memory, not a separate retrieval layer. Every agent turn, tool call, and delegation becomes a typed graph node with queryable relationships.
2. Typed Node System
- Episode - What happened (coding turn with tools, files, outcome)
- Semantic - What was learned (facts with confidence scores)
- Procedural - How to do it (reusable workflow patterns)
- Persona - Who you are (evolving developer/project traits)
- Failure - What went wrong (errors + resolutions)
3. Soft Axes Persona Evolution
Persona traits evolve through metadata-only signals without LLM overhead:
- Axes represent spectrums (verbosity: concise ↔ detailed)
- Signals apply directional force with strength
- EMA smoothing with decay prevents overfitting
- No LLM calls needed for evolution
4. Pattern Extraction and Promotion
Successful tool sequences automatically become reusable patterns:
- Detection: repeated sequences with success outcomes
- Promotion: min occurrences + fitness score threshold
- Fitness tracking: EMA of success/failure ratio
- Tool canonicalization:
bash/shell/sh→bash
5. Intelligent Compression (Eco Mode)
Embedding-free prompt compression reduces token costs:
- Balanced: ~55% retention (40-50% savings)
- Aggressive: ~35% retention (55-70% savings)
- Preserves code blocks, technical terms, user intent
- Strips filler phrases and meta-commentary
- Sub-30ms latency
6. Inbox Pattern for Multi-Writer Sync
Safe memory updates from multiple processes:
- Hooks append to lightweight capture files
- MCP server drains inbox into SQLite
- No DB locking conflicts
- Eventual consistency
See docs/AINL_CONCEPTS.md for detailed explanations.
⚙️ Configuration
The plugin works out-of-the-box with sensible defaults. Advanced users can configure:
Memory Settings
Edit mcp_server/retrieval.py:
- Memory retrieval thresholds
- Context budget limits
- Ranking algorithm weights
Persona Settings
Edit mcp_server/persona_evolution.py:
- Persona evolution axes
- Signal extraction rules
- EMA alpha (learning rate)
Pattern Settings
Edit mcp_server/extractor.py:
- Pattern promotion criteria
- Fitness thresholds
- Consolidation frequency
Logging
Edit hooks/shared/logger.py:
- Logging levels
- Output destinations
- Debug modes
🧪 Development
Running Tests
# Install dev dependencies
pip install -e ".[dev]"
# Run all tests
pytest tests/ -v
# Run specific test modules
pytest tests/test_persona_evolution.py -v
pytest tests/test_failure_learning.py -v
pytest tests/test_trajectory_capture.py -v
pytest tests/test_pattern_recurrence.py -v
# Run with coverage
pytest tests/ --cov=mcp_server --cov=hooks --cov-report=html
# View coverage report
open htmlcov/index.html
Project Structure
ainl-cortex/
├── mcp_server/ # MCP server implementation
│ ├── server.py # Main server entry point
│ ├── ainl_tools.py # AINL tool implementations
│ ├── ainl_patterns.py # Pattern management
│ ├── persona_evolution.py # Persona learning engine
│ ├── failure_learning.py # Failure resolution system
│ ├── trajectory_capture.py# Execution tracing
│ ├── context_compiler.py # Context assembly
│ ├── compression_profiles.py # Adaptive compression
│ └── improvement_proposals.py # Closed-loop validation
├── hooks/ # Claude Code hooks
│ ├── ainl_detection.py # Auto-detect AINL opportunities
│ ├── ainl_validator.py # Validate AINL files
│ └── shared/ # Shared utilities
├── cli/ # Command-line tools
│ ├── memory_cli.py # Memory inspection
│ ├── compression_cli.py # Compression management
│ └── trajectory_cli.py # Trajectory analysis
├── tests/ # Test suite
├── docs/ # Documentation
│ ├── AINL_CONCEPTS.md
│ ├── COMPRESSION_ECO_MODE.md
│ ├── ADVANCED_COMPRESSION.md
│ └── DEEP_DIVE_AINL_ARCHITECTURE.md
├── templates/ # AINL templates
└── profiles/ # Compression profiles
🤝 Contributing
Contributions welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Add tests for new functionality
- Ensure all tests pass (
pytest tests/) - Update documentation as needed
- Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Submit a pull request
See CONTRIBUTING.md for detailed guidelines.
🌐 Inspired By
This plugin is directly inspired by the AINL (AINativeLang) unified graph execution engine from the ArmaraOS project:
AINL Crates:
- ainl-memory - GraphStore trait, typed nodes, SQLite backend
- ainl-persona - Soft axes evolution, signal ingestion
- ainl-graph-extractor - Pattern detection, recurrence tracking
- ainl-runtime - Turn orchestration, memory context compilation
- ainl-semantic-tagger - Tool canonicalization
- ainl-compression - Prompt compression algorithms, eco modes
Hermes Agent Integration:
- Closed learning loop architecture
- Trajectory capture and analysis
- Strict validation gates
- Durable memory patterns
All core architectural concepts and algorithms are attributed to the AINL and Hermes projects.
📄 License
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Copyright 2026 AINativeLang, Inc.
🗺️ Roadmap
✅ v0.2 (COMPLETE)
- ✅ Trajectory capture and analysis
- ✅ Zero-LLM persona evolution
- ✅ Failure learning and prevention
- ✅ Pattern promotion and consolidation
- ✅ Adaptive compression profiles
- ✅ Context compilation
- ✅ Closed-loop validation
✅ v0.3 (Current - COMPLETE)
- ✅ Native Rust backend (
ainl_nativePyO3 extension wrapping armaraos crates) - ✅ Full
ainl-*crate integration: trajectory, persona, procedure learning, semantic tagger - ✅ Python ↔ Native backend switch via
config.json(auto-fallback if build fails) - ✅ Cross-session prompt compression via anchored summary
- ✅ Context freshness gating (
check_freshness/can_execute) at SessionStart - ✅ Procedure scoring (
score_reuse) at UserPromptSubmit - ✅ Reverse-edge graph traversal (
walk_edges_to) - ✅ Migration tooling (
migrate_to_native.py) for existing Python-backend data - ✅ PreCompact / PostCompact hooks for zero-data-loss at context compaction
- ✅ Notification feed poller — session-start banner notices with seen-ID persistence and optional auto-update
📋 v0.4 (Planned)
- Semantic embeddings for vector search (local model)
- Cross-project pattern library
- Web-based memory explorer UI
- Export/import graph snapshots
- Multi-modal trajectory visualization
- Collaborative team memory
- Advanced persona axes (domain-specific)
- Real-time learning metrics dashboard
📋 v0.5 (Vision)
- AINL IR pattern compilation
- GraphPatch integration
- Memory consolidation/pruning strategies
- Federated learning across users
- Analytics and insights dashboard
🙋 FAQ
How does this differ from other memory systems?
Traditional Memory: Separate retrieval layer, episodic/semantic silos, expensive embeddings
AINL Cortex: Execution IS memory, unified graph, zero-LLM learning, metadata-driven
Does this send data to external services?
Memory data: no. All graph memory is stored locally in SQLite. No code, prompts, file paths, or conversation content ever leaves your machine.
Anonymous usage telemetry: yes, by default. To help us understand how many people install and use the plugin, we send anonymous events to PostHog (the same analytics stack used across AINativeLang tooling). What's included: a random install ID (UUID generated at setup into gitignored config.local.json, never tied to your identity), plugin version, OS type, Python version, and which MCP tool names are called — never their arguments.
To opt out, add this to config.json:
"telemetry": { "remote": { "enabled": false } }
How much disk space does it use?
Typical usage: 1-5 MB per project with thousands of interactions. Includes automatic consolidation to prevent bloat.
Can I disable specific features?
Yes! Each feature has configuration flags:
AINL_MEMORY_ENABLED- Master switchAINL_PERSONA_EVOLUTION- Persona learningAINL_TAGGER_ENABLED- Semantic taggingAINL_LOG_TRAJECTORY- Trajectory capture
How secure is my data?
Memory is stored locally with file permissions matching your user. No cloud sync. Project-isolated databases prevent cross-contamination.
Does this work without AINL?
Yes! The graph memory system works with all Claude Code interactions. AINL integration is optional but provides additional optimization.
How do goals differ from the file-based memory system?
The file-based memory in ~/.claude/projects/.../memory/ is for human-readable facts (user preferences, project notes). Goals are typed graph nodes tied to episode clusters — they track multi-session work items, link to contributing episodes, carry status lifecycles, and auto-infer from your activity. They are complementary, not competing.
Do I need ArmaraOS to use A2A features?
You need the ArmaraOS daemon running locally for a2a_send / a2a_task_send to deliver messages. Without it the tools report a clean "bridge offline" error and fall back gracefully. a2a_note_to_self always works — it writes to a local inbox file that surfaces at next SessionStart regardless of daemon status.
What happens to memory during context compaction?
Nothing is lost. The PreCompact hook flushes all buffered captures to the graph DB and snapshots the current session state before compaction fires. The PostCompact hook then updates the anchored summary to reflect post-compact state. The next session's SessionStart injects the correct context.
💬 Support
Issues & Bugs: https://github.com/sbhooley/ainl-cortex/issues
Discussions: https://github.com/sbhooley/ainl-cortex/discussions
Email: [email protected]
Built with ❤️ by the Claude Code community
Powered by AINL architecture from ArmaraOS
AINL Cortex — the intelligent core that learns, connects, and evolves with you
🎉 Quick Example
Here's what the plugin does automatically in the background:
# 1. You ask Claude to create a health monitor
"Create an AINL workflow that checks my API every 5 minutes"
# 2. Plugin detects recurring task → suggests AINL
💡 This looks like a recurring task! I recommend AINL for 95% token savings.
# 3. Claude creates workflow.ainl (validated automatically)
✅ Created and validated workflow.ainl
# 4. You run it successfully
→ Trajectory captured
→ Pattern extracted: "health_monitor" (fitness: 1.0)
→ Persona signal: curiosity +0.15
# 5. Later, you make a typo
Error: unknown adapter 'httP'
→ Failure recorded with context
# 6. You fix it
→ Resolution stored: 'httP' → 'http'
# 7. Next time similar error happens
💡 I've seen this error 3 times. Fix: Change 'httP' to 'http'
# 8. Future similar requests
💡 I see you've created health monitors before (fitness: 0.95).
Would you like me to base this on your proven pattern?
# The system learned:
# • Your preference for AINL (persona)
# • The health monitor pattern (procedural)
# • The common typo fix (failure prevention)
# • Your coding style (persona evolution)
#
# All without a single LLM call for introspection!
That's the power of graph-as-memory with zero-LLM learning. 🚀
🌐 A2A + Goal Tracking in Action
# Session 1
"Build an auth middleware rewrite"
→ Goal auto-inferred from episode cluster:
GOAL: "Implement auth middleware rewrite" (status: active)
→ 4 episodes linked: refactor, test, validate, document
# End of session — want to pick up next time?
a2a_note_to_self("Resume auth middleware at step 3: add compliance headers")
# Session 2 opens →
[SessionStart] Note from last session:
"Resume auth middleware at step 3: add compliance headers"
→ Goal recalled: memory_list_goals → "Implement auth middleware rewrite" (active)
→ Continue seamlessly
# Want another agent to review?
a2a_send(to="ELF", message="Review the new auth middleware PR branch")
→ ELF responds
→ Exchange stored as MessageNode in graph DB for audit
# Done?
memory_complete_goal(goal_id="g_abc123",
summary="Auth middleware rewritten, compliance headers added, tests passing")
→ GOAL node marked completed
→ Contributing episodes retained in graph
Goals + A2A + graph memory = collaborative, continuous, cross-session intelligence.
