instinct-mcp 0.1.1__tar.gz

instinct_mcp-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WinstonRedGuard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

instinct_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: instinct-mcp
+Version: 0.1.1
+Summary: Self-learning memory for AI coding agents — pattern detection, confidence scoring, auto-promotion via MCP
+License: MIT
+Project-URL: Homepage, https://github.com/yakuphanycl/instinct
+Project-URL: Issues, https://github.com/yakuphanycl/instinct/issues
+Keywords: mcp,ai-agent,memory,instinct,claude-code,cursor,goose
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Dynamic: license-file
+
+<p align="center">
+  <h1 align="center">instinct</h1>
+  <p align="center">
+    <strong>Self-learning memory for AI coding agents</strong>
+  </p>
+  <p align="center">
+    <a href="https://pypi.org/project/instinct-mcp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/instinct-mcp?color=%2334D058&label=pypi"></a>
+    <a href="https://pypi.org/project/instinct-mcp/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/instinct-mcp"></a>
+    <a href="https://github.com/yakuphanycl/instinct/blob/master/LICENSE"><img alt="License" src="https://img.shields.io/github/license/yakuphanycl/instinct"></a>
+    <a href="https://modelcontextprotocol.io"><img alt="MCP" src="https://img.shields.io/badge/MCP-compatible-blue"></a>
+  </p>
+</p>
+
+---
+
+Your AI agent makes the same mistakes twice. It forgets your preferences between sessions. It doesn't learn from repetition.
+
+**instinct** fixes this. It observes patterns from your agent sessions, tracks confidence over time, and auto-promotes recurring patterns into suggestions your agent follows — without you repeating yourself.
+
+Works with any MCP-compatible agent: **Claude Code**, **Cursor**, **Windsurf**, **Goose**, **Codex**, and others.
+
+## How It Works
+
+```
+         observe           track            promote           suggest
+        ┌───────┐       ┌───────┐        ┌───────┐        ┌───────┐
+  You   │Record │  +1   │ Count │  >=5   │Mature │  >=10  │ Rule  │
+  work  │pattern├──────>│ hits  ├───────>│suggest├───────>│ auto- │
+        └───────┘       └───────┘        └───────┘        │ apply │
+                                                          └───────┘
+```
+
+1. **Observe** — record patterns as your agent works (tool sequences, preferences, recurring fixes)
+2. **Track** — each re-observation increments confidence
+3. **Promote** — confidence >= 5 becomes `mature` (suggested), >= 10 becomes `rule` (auto-applied)
+4. **Suggest** — mature patterns guide agent behavior without explicit instruction
+
+## Install
+
+```bash
+pip install instinct-mcp
+```
+
+## Quick Start
+
+### 1. Add to your agent
+
+**Claude Code** — add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "instinct": {
+      "command": "instinct",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+**Cursor / Windsurf** — add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "instinct": {
+      "command": "instinct",
+      "args": ["serve", "--transport", "sse"]
+    }
+  }
+}
+```
+
+That's it. Your agent now has access to 8 tools:
+
+| Tool | What it does |
+|------|-------------|
+| `observe` | Record a pattern (auto-increments confidence on repeat) |
+| `suggest` | Get mature patterns to guide current behavior |
+| `list_instincts` | Browse all observed patterns with filters |
+| `get_instinct` | Look up a specific pattern |
+| `consolidate` | Promote patterns that crossed confidence thresholds |
+| `search_instincts` | Full-text search across patterns and metadata |
+| `stats` | Summary statistics of the instinct store |
+| `export_rules` | Export rule-level patterns as structured data |
+
+### 2. Watch it learn
+
+As you work, your agent starts noticing patterns:
+
+```
+Session 1:  observe("seq:test->fix->test")          → confidence 1 (raw)
+Session 3:  observe("seq:test->fix->test")          → confidence 3 (raw)
+Session 5:  observe("seq:test->fix->test")          → confidence 5 (mature ✓)
+            suggest() → "When tests fail, apply fix and re-run tests"
+```
+
+After enough repetitions, instinct starts suggesting the pattern back — your agent adapts to how *you* work.
+
+## What Patterns Look Like
+
+```bash
+# Tool sequences your agent repeats
+instinct observe "seq:lint->fix->lint"
+instinct observe "seq:build->test->deploy"
+
+# Your preferences it should remember
+instinct observe "pref:style=black" --cat preference
+instinct observe "pref:commits=conventional" --cat preference
+
+# Fixes it keeps rediscovering
+instinct observe "fix:missing-import" --cat fix_pattern
+instinct observe "fix:utf8-encoding-windows" --cat fix_pattern
+
+# Tools that work better together
+instinct observe "combo:pytest+coverage" --cat combo
+```
+
+### Naming Convention
+
+| Prefix | Use for | Example |
+|--------|---------|---------|
+| `seq:` | Action sequences | `seq:lint->fix->lint` |
+| `pref:` | User preferences | `pref:style=black` |
+| `fix:` | Recurring fixes | `fix:missing-import` |
+| `combo:` | Tool combinations | `combo:pytest+coverage` |
+
+## Maturity Levels
+
+| Level | Confidence | Behavior |
+|-------|-----------|----------|
+| **raw** | < 5 | Observed, stored, not yet actionable |
+| **mature** | >= 5 | Returned by `suggest()` — agent uses as guidance |
+| **rule** | >= 10 | Exported by `export_rules()` — strong enough to auto-apply |
+
+## CLI Reference
+
+```bash
+instinct observe <pattern>       # Record/reinforce a pattern
+instinct get <pattern>           # Look up a specific pattern
+instinct list                    # List all instincts
+instinct suggest                 # Get mature suggestions
+instinct consolidate             # Auto-promote by confidence
+instinct decay                   # Reduce stale patterns (default: 90 days inactive)
+instinct stats                   # Summary statistics
+instinct export-rules            # Export rules as JSON
+instinct delete <pattern>        # Remove a pattern
+instinct fingerprint             # Print project fingerprint for cwd
+instinct serve                   # Start MCP server
+```
+
+All commands support `--json` for structured output.
+
+### Observe Options
+
+```bash
+instinct observe "seq:a->b" \
+  --cat sequence              # Category: sequence|preference|fix_pattern|combo
+  --source claude-code        # Which agent/tool recorded this
+  --project auto              # Project fingerprint (auto-detected from cwd)
+```
+
+### Server Options
+
+```bash
+instinct serve                              # stdio (default, for Claude Code)
+instinct serve --transport sse              # SSE for remote/HTTP clients
+instinct serve --transport streamable-http  # Streamable HTTP
+instinct serve --port 3777                  # Custom port (default: 3777)
+```
+
+## Python Library
+
+```python
+from instinct.store import InstinctStore
+
+store = InstinctStore()  # uses ~/.instinct/instinct.db
+
+# Record patterns
+store.observe("seq:test->fix->test", source="my-tool")
+store.observe("seq:test->fix->test")  # confidence = 2
+
+# Query
+suggestions = store.suggest()                     # mature+ patterns
+results     = store.search("test")                # full-text search
+rules       = store.export_rules()                # rule-level only
+
+# Lifecycle
+store.consolidate()                               # promote by threshold
+store.decay(days_inactive=90)                     # fade stale patterns
+
+# Stats
+print(store.stats())
+# {'total': 42, 'raw': 30, 'mature': 10, 'rules': 2, 'avg_confidence': 4.2, ...}
+```
+
+### Custom Database Path
+
+```python
+store = InstinctStore(db_path="/path/to/custom.db")
+```
+
+## Cross-Project Learning
+
+instinct hashes your working directory into a project fingerprint. This means:
+
+- **Project-specific patterns** are only suggested when you're in that project
+- **Global patterns** (empty project field) are suggested everywhere
+
+```bash
+# See your current project's fingerprint
+instinct fingerprint
+# → a1b2c3d4e5f6
+```
+
+## Storage
+
+- **Database:** SQLite at `~/.instinct/instinct.db`
+- **Dependencies:** Only `mcp>=1.0.0`
+- **Size:** ~650 lines of Python, zero bloat
+
+## How It Compares
+
+| | instinct | Manual CLAUDE.md | .cursorrules |
+|---|---|---|---|
+| Learns automatically | Yes | No | No |
+| Cross-session memory | Yes | Yes | Yes |
+| Confidence scoring | Yes | No | No |
+| Decay of stale patterns | Yes | No | No |
+| Works across agents | Yes (MCP) | Claude only | Cursor only |
+| Requires manual editing | No | Yes | Yes |
+
+## License
+
+[MIT](LICENSE)

instinct_mcp-0.1.1/README.md

@@ -0,0 +1,235 @@
+<p align="center">
+  <h1 align="center">instinct</h1>
+  <p align="center">
+    <strong>Self-learning memory for AI coding agents</strong>
+  </p>
+  <p align="center">
+    <a href="https://pypi.org/project/instinct-mcp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/instinct-mcp?color=%2334D058&label=pypi"></a>
+    <a href="https://pypi.org/project/instinct-mcp/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/instinct-mcp"></a>
+    <a href="https://github.com/yakuphanycl/instinct/blob/master/LICENSE"><img alt="License" src="https://img.shields.io/github/license/yakuphanycl/instinct"></a>
+    <a href="https://modelcontextprotocol.io"><img alt="MCP" src="https://img.shields.io/badge/MCP-compatible-blue"></a>
+  </p>
+</p>
+
+---
+
+Your AI agent makes the same mistakes twice. It forgets your preferences between sessions. It doesn't learn from repetition.
+
+**instinct** fixes this. It observes patterns from your agent sessions, tracks confidence over time, and auto-promotes recurring patterns into suggestions your agent follows — without you repeating yourself.
+
+Works with any MCP-compatible agent: **Claude Code**, **Cursor**, **Windsurf**, **Goose**, **Codex**, and others.
+
+## How It Works
+
+```
+         observe           track            promote           suggest
+        ┌───────┐       ┌───────┐        ┌───────┐        ┌───────┐
+  You   │Record │  +1   │ Count │  >=5   │Mature │  >=10  │ Rule  │
+  work  │pattern├──────>│ hits  ├───────>│suggest├───────>│ auto- │
+        └───────┘       └───────┘        └───────┘        │ apply │
+                                                          └───────┘
+```
+
+1. **Observe** — record patterns as your agent works (tool sequences, preferences, recurring fixes)
+2. **Track** — each re-observation increments confidence
+3. **Promote** — confidence >= 5 becomes `mature` (suggested), >= 10 becomes `rule` (auto-applied)
+4. **Suggest** — mature patterns guide agent behavior without explicit instruction
+
+## Install
+
+```bash
+pip install instinct-mcp
+```
+
+## Quick Start
+
+### 1. Add to your agent
+
+**Claude Code** — add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "instinct": {
+      "command": "instinct",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+**Cursor / Windsurf** — add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "instinct": {
+      "command": "instinct",
+      "args": ["serve", "--transport", "sse"]
+    }
+  }
+}
+```
+
+That's it. Your agent now has access to 8 tools:
+
+| Tool | What it does |
+|------|-------------|
+| `observe` | Record a pattern (auto-increments confidence on repeat) |
+| `suggest` | Get mature patterns to guide current behavior |
+| `list_instincts` | Browse all observed patterns with filters |
+| `get_instinct` | Look up a specific pattern |
+| `consolidate` | Promote patterns that crossed confidence thresholds |
+| `search_instincts` | Full-text search across patterns and metadata |
+| `stats` | Summary statistics of the instinct store |
+| `export_rules` | Export rule-level patterns as structured data |
+
+### 2. Watch it learn
+
+As you work, your agent starts noticing patterns:
+
+```
+Session 1:  observe("seq:test->fix->test")          → confidence 1 (raw)
+Session 3:  observe("seq:test->fix->test")          → confidence 3 (raw)
+Session 5:  observe("seq:test->fix->test")          → confidence 5 (mature ✓)
+            suggest() → "When tests fail, apply fix and re-run tests"
+```
+
+After enough repetitions, instinct starts suggesting the pattern back — your agent adapts to how *you* work.
+
+## What Patterns Look Like
+
+```bash
+# Tool sequences your agent repeats
+instinct observe "seq:lint->fix->lint"
+instinct observe "seq:build->test->deploy"
+
+# Your preferences it should remember
+instinct observe "pref:style=black" --cat preference
+instinct observe "pref:commits=conventional" --cat preference
+
+# Fixes it keeps rediscovering
+instinct observe "fix:missing-import" --cat fix_pattern
+instinct observe "fix:utf8-encoding-windows" --cat fix_pattern
+
+# Tools that work better together
+instinct observe "combo:pytest+coverage" --cat combo
+```
+
+### Naming Convention
+
+| Prefix | Use for | Example |
+|--------|---------|---------|
+| `seq:` | Action sequences | `seq:lint->fix->lint` |
+| `pref:` | User preferences | `pref:style=black` |
+| `fix:` | Recurring fixes | `fix:missing-import` |
+| `combo:` | Tool combinations | `combo:pytest+coverage` |
+
+## Maturity Levels
+
+| Level | Confidence | Behavior |
+|-------|-----------|----------|
+| **raw** | < 5 | Observed, stored, not yet actionable |
+| **mature** | >= 5 | Returned by `suggest()` — agent uses as guidance |
+| **rule** | >= 10 | Exported by `export_rules()` — strong enough to auto-apply |
+
+## CLI Reference
+
+```bash
+instinct observe <pattern>       # Record/reinforce a pattern
+instinct get <pattern>           # Look up a specific pattern
+instinct list                    # List all instincts
+instinct suggest                 # Get mature suggestions
+instinct consolidate             # Auto-promote by confidence
+instinct decay                   # Reduce stale patterns (default: 90 days inactive)
+instinct stats                   # Summary statistics
+instinct export-rules            # Export rules as JSON
+instinct delete <pattern>        # Remove a pattern
+instinct fingerprint             # Print project fingerprint for cwd
+instinct serve                   # Start MCP server
+```
+
+All commands support `--json` for structured output.
+
+### Observe Options
+
+```bash
+instinct observe "seq:a->b" \
+  --cat sequence              # Category: sequence|preference|fix_pattern|combo
+  --source claude-code        # Which agent/tool recorded this
+  --project auto              # Project fingerprint (auto-detected from cwd)
+```
+
+### Server Options
+
+```bash
+instinct serve                              # stdio (default, for Claude Code)
+instinct serve --transport sse              # SSE for remote/HTTP clients
+instinct serve --transport streamable-http  # Streamable HTTP
+instinct serve --port 3777                  # Custom port (default: 3777)
+```
+
+## Python Library
+
+```python
+from instinct.store import InstinctStore
+
+store = InstinctStore()  # uses ~/.instinct/instinct.db
+
+# Record patterns
+store.observe("seq:test->fix->test", source="my-tool")
+store.observe("seq:test->fix->test")  # confidence = 2
+
+# Query
+suggestions = store.suggest()                     # mature+ patterns
+results     = store.search("test")                # full-text search
+rules       = store.export_rules()                # rule-level only
+
+# Lifecycle
+store.consolidate()                               # promote by threshold
+store.decay(days_inactive=90)                     # fade stale patterns
+
+# Stats
+print(store.stats())
+# {'total': 42, 'raw': 30, 'mature': 10, 'rules': 2, 'avg_confidence': 4.2, ...}
+```
+
+### Custom Database Path
+
+```python
+store = InstinctStore(db_path="/path/to/custom.db")
+```
+
+## Cross-Project Learning
+
+instinct hashes your working directory into a project fingerprint. This means:
+
+- **Project-specific patterns** are only suggested when you're in that project
+- **Global patterns** (empty project field) are suggested everywhere
+
+```bash
+# See your current project's fingerprint
+instinct fingerprint
+# → a1b2c3d4e5f6
+```
+
+## Storage
+
+- **Database:** SQLite at `~/.instinct/instinct.db`
+- **Dependencies:** Only `mcp>=1.0.0`
+- **Size:** ~650 lines of Python, zero bloat
+
+## How It Compares
+
+| | instinct | Manual CLAUDE.md | .cursorrules |
+|---|---|---|---|
+| Learns automatically | Yes | No | No |
+| Cross-session memory | Yes | Yes | Yes |
+| Confidence scoring | Yes | No | No |
+| Decay of stale patterns | Yes | No | No |
+| Works across agents | Yes (MCP) | Claude only | Cursor only |
+| Requires manual editing | No | Yes | Yes |
+
+## License
+
+[MIT](LICENSE)

instinct_mcp-0.1.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "instinct-mcp"
+version = "0.1.1"
+description = "Self-learning memory for AI coding agents — pattern detection, confidence scoring, auto-promotion via MCP"
+requires-python = ">=3.11"
+readme = "README.md"
+keywords = ["mcp", "ai-agent", "memory", "instinct", "claude-code", "cursor", "goose"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
+license = {text = "MIT"}
+dependencies = [
+    "mcp>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/yakuphanycl/instinct"
+Issues = "https://github.com/yakuphanycl/instinct/issues"
+
+[project.scripts]
+instinct = "instinct.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

instinct_mcp-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

instinct_mcp-0.1.1/src/instinct/__init__.py

@@ -0,0 +1,2 @@
+"""instinct — Self-learning memory for AI coding agents."""
+__version__ = "0.1.1"