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?

Capability	Status	Implemented as
MCP server	Real	ai-rule-learning-mcp entry point
CLI	Real	ai-rule-learning entry point
Guardrail rules	Real	Local JSONL storage plus injected markdown blocks
Memory	Real	Local JSONL storage plus injected markdown blocks
Skills	Real	Local markdown skill files plus injected skill index
Agent config injection	Real	Claude Code, Cursor, Windsurf, and GitHub Copilot targets
Auto-sync scheduler	Real	LaunchAgent, systemd user timer, or cron fallback
Decision-rule mining API	Not current API	The current package exposes MCP tools and CLI commands instead.

---

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

Tool	What it does
get_guardrail_rules	Returns active guardrail rules as a formatted text block.
record_feedback	Generates a rule from session feedback such as corrections or repeated context.
sync_sessions	Parses supported local session files, detects patterns, and refreshes injected rules.
remember	Stores a preference, project detail, hard constraint, user fact, or context item.
recall	Reads stored memory entries.
save_skill	Saves a reusable workflow.
list_skills	Lists saved workflows.
get_skill	Retrieves a saved workflow by name or keyword.
install_scheduler	Installs, uninstalls, or checks the nightly sync scheduler.
list_providers	Shows detected session sources and agent config targets.
list_rules	Lists stored rules by lifecycle status.
approve_rule	Approves and activates a reviewed rule.
reject_rule	Rejects a rule so it is not injected.
edit_rule	Updates a rule instruction.
merge_rules	Marks a duplicate rule as merged into a primary rule.
record_rule_outcome	Tracks whether a rule worked or failed.
review_rule_health	Finds stale or low-effectiveness rules and can mark them for review.
suggest_duplicate_rules	Suggests likely duplicate rules for explicit review and merge.
analyze	Reports health, failure modes, injection checks, and rule-effectiveness data.

---

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.

Agent	Config file
Claude Code	~/.claude/CLAUDE.md
Cursor	~/.cursor/rules/ai-guardrails.md
Windsurf	~/.windsurf/rules/ai-guardrails.md
GitHub Copilot	~/.config/github-copilot/instructions.md

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:

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

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:

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

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:

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

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.