AI Rule Learning MCP

AI Rule Learning MCP is a local MCP server and CLI for turning repeated AI-session feedback into persistent guardrails, memory, and reusable skills that can be injected into supported AI-agent configuration files.

This README describes what is implemented in this repository today. Earlier decision-rule mining examples have been removed because those public classes are not part of the current package API.

What is real today?

Installation

pip install ai-rule-learning-mcp

Note on MCP SDK Compatibility: Compatible with mcp>=1.0.0,<2.0.0. See MCP Versioning Guide for details on supported SDK versions and the 2.x migration path.

Run the MCP server:

ai-rule-learning-mcp

Run the CLI directly:

ai-rule-learning status

MCP setup

Add the server to an MCP-compatible client configuration:

{
  "mcpServers": {
    "ai-rule-learning": {
      "command": "ai-rule-learning-mcp"
    }
  }
}

CLI commands

# Scan sessions and generate rules
ai-rule-learning sync

# Preview sync without writing local storage or agent config files
ai-rule-learning sync --dry-run

# Show current rules and detected agent configs
ai-rule-learning status

# Print active rules
ai-rule-learning rules

# Review and manage rule lifecycle
ai-rule-learning rules pending
ai-rule-learning rules approve <rule-id>
ai-rule-learning rules reject <rule-id>
ai-rule-learning rules edit <rule-id> "Always run focused tests first"
ai-rule-learning rules merge <primary-rule-id> <duplicate-rule-id>
ai-rule-learning rules outcome <rule-id> --worked
ai-rule-learning rules outcome <rule-id> --failed
ai-rule-learning rules health
ai-rule-learning rules health --apply
ai-rule-learning rules duplicates

# Remove all injected sections
ai-rule-learning clear

# Preview destructive/write operations before changing files
ai-rule-learning clear --dry-run

# Memory
ai-rule-learning memory show
ai-rule-learning memory add preference "Always use type hints in Python"
ai-rule-learning memory add preference "Always use type hints in Python" --dry-run
ai-rule-learning memory clear
ai-rule-learning memory clear --dry-run

# Skills
ai-rule-learning skills
ai-rule-learning skills show "Deploy Workflow"
ai-rule-learning skills delete "Old Workflow"

# Auto-sync scheduler
ai-rule-learning install-cron
ai-rule-learning cron-status
ai-rule-learning uninstall-cron
ai-rule-learning install-cron --dry-run
ai-rule-learning uninstall-cron --dry-run

# Privacy-preserving opt-in metrics
ai-rule-learning metrics status
ai-rule-learning metrics preview
ai-rule-learning metrics enable
ai-rule-learning metrics disable

These commands are implemented by the ai-rule-learning console script.

Usage metrics are disabled by default. If you opt in, the CLI records only anonymous aggregate labels such as command/tool names, success/failure counts, package version, Python version bucket, and OS family. It never records prompts, rule text, memory content, file paths, usernames, repo names, hostnames, or agent config content. Run ai-rule-learning metrics preview before enabling sharing to inspect the exact aggregate payload.

MCP tools

What gets written where

Rules, memory, and skills are injected as fenced markdown blocks using HTML comment markers into every detected supported AI-agent config.

All sections are idempotent: re-running sync updates existing blocks instead of duplicating them.

Remove injected sections with:

ai-rule-learning clear

Local storage

All local data is stored under ~/.ai-rule-learning/:

~/.ai-rule-learning/
  rules.jsonl          Active guardrail rules
  memory.jsonl         Remembered facts and preferences
  conversations.jsonl  Parsed session history
  processed.jsonl      Deduplication index
  skills/              Saved skill procedures, one markdown file per skill
  sync.log             Auto-sync output

Auto-sync scheduler

The scheduler is opt-in. It is only installed when you run:

ai-rule-learning install-cron

Depending on your OS, the package uses one of these mechanisms:

Check scheduler status:

Check scheduler status:

```bash

The scheduler is opt-in. It is only installed when you run:

```bash
ai-rule-learning install-cron

Depending on your OS, the package uses one of these mechanisms:

Check scheduler status:

The scheduler is opt-in. It is only installed when you run:

```bash
ai-rule-learning install-cron

Depending on your OS, the package uses one of these mechanisms:

Check scheduler status:

ai-rule-learning cron-status

Remove scheduler automation:

| OS    | Mechanism                                         |
| ----- | ------------------------------------------------- |
| macOS | LaunchAgent                                       |
| Linux | systemd user timer when available, otherwise cron |
| Other | cron fallback when available                      |

Check scheduler status:

```bash
ai-rule-learning cron-status

Remove scheduler automation:

ai-rule-learning uninstall-cron
ai-rule-learning install-cron --dry-run
ai-rule-learning uninstall-cron --dry-run

Supported session inputs

The sync command can parse supported local conversation/session files, including Claude Code JSONL sessions and generic JSONL-style session exports. You can pass a path explicitly:

ai-rule-learning sync ~/.claude/projects

If no path is passed, the CLI checks known default local session locations.

Safety notes

• The tool writes local files when you run write operations such as sync, remember, save_skill, clear, or scheduler commands.
• The tool updates supported agent config files using explicit HTML comment markers.
• Scheduler installation is opt-in and reversible.
• Use --dry-run on write or destructive CLI commands to preview changes before files are modified.
• MCP write tools also accept dry_run: true for safe previews of rule refreshes, feedback capture, session sync, memory writes, skill saves, and scheduler install/uninstall actions.
• Review generated rules before relying on them for critical workflows; use ai-rule-learning rules pending, approve, reject, edit, merge, and outcome to manage lifecycle state.
• Do not store secrets as memory entries or skill content.

Blue-green deployments

Production Space releases can be staged in an idle blue/green Hugging Face Space, smoke-tested, and then cut over through a router webhook with a manual approval gate. See Blue-Green Deployment Strategy for environment variables, rollback commands, and migration rules.

Development

Install development dependencies from the repository root, then run checks:

python -m pip install -r requirements-dev.txt
ruff format --check .
npm run format:check
ruff check .
mypy src
pytest
python -m pytest -c /dev/null mcp/tests -q

License

See LICENSE and TERMS.md in this repository.