ainl-cortex

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:

1. Graph-Native Memory - Persistent, queryable knowledge graph where execution history becomes searchable knowledge
2. Zero-LLM Learning - Learns your preferences and patterns without expensive LLM introspection
3. First-Class AINL Integration - Full support for AI Native Lang workflows with automatic optimization
4. 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 in logs/hook_metrics.jsonl; repartition + integrity: scripts/repartition_by_repo.py, scripts/verify_repartition_integrity.py (see scripts/MIGRATION.md)
• ✅ Cost control - Conversation-only gate, cost_profile presets, eco ledger (cortex_cost_snapshot MCP), tool digests — see docs/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 with a2a_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 / abandoned with 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/notifications once 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-only automatically 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.json under enabledPlugins
• 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-rust is passed (or you answer 1 to the interactive prompt). When stdin is not a tty (CI, agent invocation) the default is python-only — no surprise rustup.
• Installs ainl_native from PyPI (platform wheels; no Rust required on macOS/Linux/Windows). Falls back to maturin develop only if the wheel is unavailable and Rust is installed. Does not flip store_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 /mcp will list ~30 new tools."

Step 3 — Verify after restart

After the user restarts, confirm the install worked by checking:

1. 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.
2. Running /mcp in Claude Code lists tools prefixed ainl-cortex__. The exact count depends on installed extras and config:
   • 30 tools = 11 memory + 12 AINL + 7 A2A (default install with ainativelang[mcp] and a2a.enabled = true).
   • 23 tools = 11 memory + 12 AINL when A2A is disabled (a2a.enabled = false in config.json, the install default — A2A tools are hidden until you opt in).