Metadata-Version: 2.4
Name: ai-rule-learning-mcp
Version: 0.2.0
Summary: MCP server that learns guardrail rules from your AI conversations and injects them automatically
Author-email: Fahad JUB <info@tococolors.com>
License: Source Available — free for personal use, commercial/government use requires written permission. See https://github.com/faju85/ai_rule_learning/blob/main/LICENSE
Project-URL: Homepage, https://github.com/faju85/ai_rule_learning
Project-URL: Repository, https://github.com/faju85/ai_rule_learning
Project-URL: Bug Tracker, https://github.com/faju85/ai_rule_learning/issues
Keywords: mcp,claude,guardrails,ai,rules,llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: huggingface-hub>=0.23.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

# AI Rule Learning — MCP

Your AI remembers what works and what doesn't — and gets better every session.

AI Rule Learning watches your AI conversations, learns from the moments where
things didn't go as expected, and automatically applies that knowledge to
future sessions. The result is an AI that progressively adapts to the way you
work, without you having to change anything.

---

## Five pillars

| Pillar        | What it does                                                                             |
| ------------- | ---------------------------------------------------------------------------------------- |
| **Rules**     | Detects friction patterns and generates guardrail rules automatically                    |
| **Memory**    | Persists facts, preferences, and context across all sessions                             |
| **Skills**    | Saves and retrieves reusable multi-step workflows                                        |
| **Injection** | Writes rules, memory, and skills into Claude Code, Cursor, Windsurf, and Copilot configs |
| **Auto-sync** | Installs a nightly cron/systemd job to keep everything current                           |

## MCP tools

| Tool                         | Description                                                                          |
| ---------------------------- | ------------------------------------------------------------------------------------ |
| `get_guardrail_rules`        | Return active rules for the current session                                          |
| `record_feedback`            | Create a rule immediately from in-session feedback                                   |
| `sync_sessions`              | Parse conversation history and generate new rules                                    |
| `remember`                   | Store a fact or preference in persistent memory                                      |
| `recall`                     | Search memory for relevant context                                                   |
| `save_skill`                 | Save a reusable workflow                                                             |
| `list_skills`                | List saved skills with optional keyword filter                                       |
| `get_skill`                  | Retrieve a specific skill by name                                                    |
| `install_scheduler`          | Install the nightly auto-sync job                                                    |
| `list_providers`             | Show detected conversation history locations                                         |
| `analyze`                    | Session health, failure modes, injection check, effectiveness, and outcome recording |
| `update_community_knowledge` | Aggregate contributed gap patterns into community templates (maintainer/RAG)         |

## What it detects

### Conversation patterns

- Explicit corrections ("that's wrong", "actually,")
- Repeated context ("I already told you", "as I said")
- Incomplete responses ("you forgot", "you missed", "what about")
- Repeated questions (word-overlap across turns)
- Sycophancy — position reversals after user pushback
- Hallucination risk signals ("I think", "I believe", unverified claims)
- Overconfidence ("definitely", "certainly", "guaranteed")
- Prompt injection attempts ("ignore previous instructions", "jailbreak")
- Format failures — unexpected schema changes across turns
- Reasoning gaps — conclusions without supporting evidence

### Code quality

- Code without error handling
- Bare `except:` clauses
- `eval()` usage
- Hardcoded API keys and secrets

### Failure taxonomy

Every detected gap is tagged with a Planit failure layer (L1 Model Behaviour → L4 Human & Trust)
and a Composo failure category (e.g. `behavioral_alignment`, `safety_security`) for structured
analysis.

## The `analyze` tool

The `analyze` tool is a single combined endpoint with six actions:

| Action            | What it returns                                                               |
| ----------------- | ----------------------------------------------------------------------------- |
| `all`             | Full report: session health + failure modes + effectiveness + injection check |
| `session_health`  | 0–100 health score with per-layer gap counts and deductions                   |
| `failure_modes`   | Active rules grouped by Planit layer and Composo category                     |
| `effectiveness`   | Green / amber / red breakdown of rule effectiveness scores                    |
| `check_injection` | Scan a prompt string for injection and jailbreak patterns                     |
| `record_outcome`  | Update a rule's effectiveness score after observing it fire or be suppressed  |

Example (Claude Code tool call):

```json
{ "name": "analyze", "arguments": { "action": "all", "prompt": "<user message>" } }
```

## Works with

- Claude Code, Claude Desktop
- ChatGPT / OpenAI exports
- Cursor and Windsurf
- GitHub Copilot
- Any AI tool that exports conversation history

## Installation

```bash
pip install ai-rule-learning-mcp
```

## Quick start

```bash
# Run the MCP server (add to your agent config)
ai-rule-learning-mcp

# Or use the CLI directly
ai-rule-learning sync          # scan sessions and generate rules
ai-rule-learning rules         # show active rules
ai-rule-learning status        # show storage status
ai-rule-learning memory show   # show persistent memory
ai-rule-learning skills list   # show saved skills
ai-rule-learning install-cron  # set up nightly auto-sync
```

## What this tool changes on your machine

So there are no surprises, this tool actively writes to your system. Specifically it:

- **Writes to your AI-agent config files.** Learned rules, memory, and skills are
  injected into every detected agent config (see [Agent config paths](#agent-config-paths)
  below) so they apply to future sessions. Use `ai-rule-learning clear` to remove
  everything it wrote.
- **Stores data locally** under `~/.ai-rule-learning/` (see [Local storage](#local-storage)).
- **Installs a background job** when you run `install_scheduler` / `install-cron` — a
  nightly cron, systemd timer, or launchd agent that re-runs sync. It is **opt-in**
  (never installed automatically) and removable with `ai-rule-learning uninstall-cron`
  or the `install_scheduler` tool with `action: "uninstall"`.
- **Uploads only if you opt in.** Cloud backup/sync requires both `HF_TOKEN` and
  `ARL_DATASET`. Community contribution is **off by default** (`ARL_CONTRIBUTE=false`)
  and shares only anonymised pattern counts — never raw conversation content
  (see [Privacy](#privacy)).

Rules are always re-checked against a safety gate before being written to any config,
so unsafe instructions (e.g. "ignore all previous instructions") are filtered out.

## Agent config paths

| Agent          | Config file                          |
| -------------- | ------------------------------------ |
| Claude Code    | `~/.claude/CLAUDE.md`                |
| Cursor         | `.cursor/rules` in the project root  |
| Windsurf       | `.windsurfrules` in the project root |
| GitHub Copilot | `.github/copilot-instructions.md`    |

## Local storage

Everything lives under `~/.ai-rule-learning/`:

```text
~/.ai-rule-learning/
  rules.jsonl          # learned guardrail rules
  memory.jsonl         # persistent memory facts
  processed.jsonl      # record of processed sessions
  skills/              # saved workflows (one .md file each)
```

## Privacy

Conversation content is scrubbed locally (email, home paths, IPs, tokens)
before any storage. Community contributions (opt-in) share only anonymous
pattern counts — never your actual conversations or content.

See [PRIVACY.md](https://github.com/faju85/ai_rule_learning/blob/main/PRIVACY.md)
for full details.

## Licence

Free for personal use. Commercial and government use requires written
permission. See [LICENSE](https://github.com/faju85/ai_rule_learning/blob/main/LICENSE)
and [TERMS.md](https://github.com/faju85/ai_rule_learning/blob/main/TERMS.md).

---

> **For organisations and teams:** a business version is available by
> pre-order. Contact <info@tococolors.com> to request access.
