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 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:

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 /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).
- 18 tools = 11 memory + 7 A2A when ainativelang[mcp] is missing (AINL tools silently disabled).
- 11 tools = memory only (both AINL and A2A unavailable).

Troubleshooting — fix these before reporting failure

Symptom	Fix
`python3: command not found`	Ask user to install Python 3.10+ from python.org, then re-run `bash setup.sh`
Fewer tools visible than expected (no `ainl_*` tools)	`cd ~/.claude/plugins/ainl-cortex && .venv/bin/pip install 'ainativelang[mcp]>=1.8.0'` then restart Claude Code
No `a2a_*` tools visible	A2A is opt-in. Set `"a2a": {"enabled": true}` in `config.json` and restart Claude Code (the daemon must also be reachable).
No banner at session start	Check `~/.claude/settings.json` has `"ainl-cortex@ainl-local": true` under `enabledPlugins`; if missing, re-run `bash setup.sh`
Banner shows `MCP stack: FAIL`	Run `cd ~/.claude/plugins/ainl-cortex && bash setup.sh` again — setup re-installs deps
`ainl_native (Rust bindings): build failed`	Re-run `bash scripts/install_ainl_native.sh` or `bash setup.sh`. PyPI wheels cover macOS/Linux/Windows; Rust is only needed on unsupported platforms.
`No module named node_types` / import errors on memory tools	Auto-healed by `mcp_server/runtime_bootstrap.py` (see `docs/SELF_HEALING.md`). Preflight: `scripts/ensure_runtime_preflight.py`. Smoke: steps [0b]–[0e]. After `git pull`, restart Claude Code once if SessionStart shows a stale-MCP banner.
Missing `ainl_*` MCP tools	SessionStart + first `ainl_*` call run `pip install` into the plugin venv automatically. If still missing: `bash setup.sh`.
Stale MCP after `git pull` / setup	SessionStart banner recommends `/reload-plugins` first (then full restart if needed). Auto-update and preflight call `request_mcp_reload()`.
Native backend + unmigrated Python data	When `store_backend=native`, SessionStart auto-runs `migrate_python_to_native.sh` (24h cooldown). Opt out: `"auto_migrate_to_native": false`.

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:

`memory.project_isolation_mode`	Resolver
`per_repo` (default)	`git -C <cwd> rev-parse --show-toplevel` → `sha256(toplevel)[:16]`. Falls back to `sha256(cwd)[:16]` for non-git directories. Two clones of the same repo share state; two unrelated repos do not.
`global`	Returns the legacy `sha256("~/.claude")[:16]` for back-compat. All projects share one bucket — this was the pre-0.4 default and is now an explicit opt-in.

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-memory and related armaraos crates via PyO3 bindings compiled into ainl_native.so
Unlocks the full Rust ainl-* learning stack:
- AinlTrajectoryBuilder — properly-typed TrajectoryStep records
- cluster_experiences → build_experience_bundle → distill_procedure — Rust procedure learning pipeline
- AinlPersonaEngine — Rust persona evolution (vs Python EMA fallback)
- tag_turn — semantic tagging at 0.04ms/call
- check_freshness / can_execute — context freshness gating at SessionStart
- score_reuse — ranks procedural patterns against the current prompt
- upsert_anchored_summary / fetch_anchored_summary — cross-session prompt compression
Data stored in ainl_native.db (Rust schema) alongside ainl_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

Feature	Python Backend	Native Backend
Episode, Semantic, Procedural, Failure nodes	✅	✅
Persona evolution	Python EMA	Rust `AinlPersonaEngine`
Trajectory capture	JSONL buffer → dict	`AinlTrajectoryBuilder` → typed `TrajectoryStep`
Pattern promotion	Python `PatternExtractor`	`cluster_experiences` → `distill_procedure`
Procedure ranking	—	`score_reuse()` vs current prompt
Semantic tagging	—	`tag_turn()` 0.04ms/call
Context freshness	—	`check_freshness` / `can_execute` at SessionStart
Prompt compression (anchored summary)	✅	✅ (stored in `ainl_native.db`)
Graph traversal (reverse edges)	✅	✅ (`walk_edges_to`)

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:

Tool	What it does
`a2a_send`	Deliver a message to a named agent; returns response
`a2a_list_agents`	Discover registered agents and reachability
`a2a_register_agent`	Add a new agent by name, URL, and capability tags
`a2a_note_to_self`	Write a note that appears in the next session's context
`a2a_register_monitor`	Watch files/URLs; push A2A notification on trigger
`a2a_task_send`	Delegate an async task; get a task_id for polling
`a2a_task_status`	Check status of a delegated task

🔔 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_at in 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: true and artifact: "ainl-cortex"
Specifies a min_version / max_version range 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 p

Ainl Cortex

README

AINL Cortex for Claude Code

🌟 What is This?

🎯 Key Innovation

✨ Features at a Glance

Core Memory System

Self-Learning Capabilities (New!)

AINL Integration

A2A Multi-Agent Coordination

Goal Tracking

Zero-Loss Context Compaction

Notification Feed

⚡ Install in 30 Seconds

Backup and reinstall

🤖 For AI Agents — Complete Install Instructions

Step 1 — Clone and run setup

Step 2 — Tell the user to restart Claude Code

Step 3 — Verify after restart

Troubleshooting — fix these before reporting failure

What activates automatically (no config needed)

📐 Architecture Overview

High-Level System Architecture

Self-Learning Loop

Memory Node Types

🚀 Quick Start

Installation

What you'll see

🗂️ Project Isolation

⚙️ Backend Selection: Python vs Native (Rust)

Python Backend (default for new installs)

Native Backend (Rust — higher fidelity)

Prerequisites for the Native Backend

Auto-Build at SessionStart

Feature Comparison

Migrating Existing Data from Python to Native

🎓 How It Works

1. Trajectory Capture

2. Zero-LLM Persona Evolution

3. Pattern Recognition & Promotion

4. Failure Learning & Prevention

5. Context Compilation

6. Goal Tracking

7. A2A Multi-Agent Coordination

🔔 Notification Feed

What you'll see

How filtering works

Configuration

Auto-update (opt-in)

🛠️ Usage & CLI Tools

Inspecting Memory

Managing Compression

Advanced Compression Features

Comments (0)