instinct
The instinct server is a self-learning memory system for AI coding agents that records behavioral patterns, scores them by confidence, and surfaces mature guidance back through MCP.
Core Pattern Management
observe– Record or reinforce a behavioral pattern (tool sequences, user preferences, recurring fixes, combos); repeated observations increment confidencesuggest– Retrieve mature patterns (confidence ≥ 5) to guide current agent behavior, sorted by confidencelist_instincts– Browse all recorded patterns including low-confidence seedlings, with filters for category, project, and minimum confidenceget_instinct– Fetch the full record for a single pattern by its exact keysearch_instincts– Full-text search across pattern keys, metadata, and explain text using SQLite FTS5
Learning & Promotion
consolidate– Re-evaluate and promote patterns across tiers (raw→mature→rule→universal) based on confidence thresholds; also runs chain detection and rebuilds FTS indexdetect_chains– Automatically mine the observation log to discover sequential tool-chain patterns (seq:A->B)session_summary– End-of-session digest showing recent activity, top mature suggestions, and store stats (also runs consolidate)
Analytics & Monitoring
stats– Total patterns, level distribution, category breakdown, average/peak confidenceeffectiveness– Measure how often suggested patterns were later reinforced by anobserve()calltrending– Rank patterns by observation velocity within a time windowhistory– Show how a single pattern's confidence evolved over time
Export & Integration
export_rules– Export rule-level and universal patterns as structured JSONexport_claude_md– Render rule-level patterns as Markdown ready to paste intoCLAUDE.mdinject_claude_md– Idempotently write rule-level patterns into an existingCLAUDE.mdfile via marker tagsexport_skill– Package rules as aSKILL.mdfile in the anthropics/skills formatexport_platform– Render rules in platform-specific formats: Cursor (.cursorrules), Windsurf (.windsurfrules), Codex (AGENTS.md), or Claude MD
Import & Bulk Operations
import_patterns– Bulk-insert many patterns in one callimport_claude_md– Parse an existingCLAUDE.mdfile and ingest its instinct patterns to bootstrap the store
Store Maintenance
alias_pattern– Redirect future observations of one pattern key onto another (merge duplicates without losing confidence)find_duplicates– Detect near-identical pattern keys using token overlap similarity scoringgc/housekeep– Run all store maintenance: decay stale patterns, merge near-duplicates, clean orphan aliases, and rebuild the FTS index
Integrates with GitHub Actions for CI/CD workflows and Dependabot for dependency updates, with repository health monitoring and protected branch management.
Provides CI/CD workflow integration with automated testing and security scanning through GitHub Actions workflows.
Supports export and import of patterns to/from Markdown files (CLAUDE.md, SKILL.md) for agent instruction formatting.
Supports pattern detection for pytest testing workflows, including test sequences and combination patterns with coverage tools.
Provides Python-specific pattern learning and memory capabilities for AI coding agents working with Python projects and tools.
Uses SQLite for pattern storage with full-text search capabilities, backup/restore functionality, and database health management.
Supports TOML configuration format for MCP server setup with certain AI agent clients like Codex CLI.
instinct
💡 Found this useful? ⭐ Star the repo (helps others find it) and subscribe to weekly detection-engineering writeups at Detection Frontier.
Self-learning memory for AI coding agents: record repeated patterns, score them by confidence, and surface mature guidance back through MCP.
Records tool sequences, user preferences, recurring fixes, and useful tool combinations.
Promotes repeated observations from
rawtomature,rule, and cross-projectuniversal.Exports learned rules for Claude, Cursor, Windsurf, Codex, CLAUDE.md, and Agent Skills.
Current release: 1.4.1 (April 2026; transferred to WRG-11 org). Python >=3.11. SQLite WAL storage at ~/.instinct/instinct.db. Single runtime dep (mcp>=1.0.0).
pip install instinct-mcpLive install stats: pypistats.org/packages/instinct-mcp.
Quick Start
For Claude Code:
pip install instinct-mcp
claude mcp add instinct -- instinct serve
instinct observe "seq:test->fix->test"Then ask your agent for suggestions, or run:
instinct suggestSuggestions appear once a pattern reaches mature confidence. By default,
mature starts at confidence 5 and rule starts at confidence 10.
What It Learns
You feed instinct one observe call per recurring behaviour you want it to remember.
Each call increments confidence on the matching pattern; once confidence reaches the
mature threshold (default: 5), the pattern shows up in suggest and can be exported
back into your agent's rule files. Four prefix conventions help organise + search the
store:
instinct observe "seq:lint->fix->lint" # tool-sequence patterns
instinct observe "pref:commits=conventional" # user preferences
instinct observe "fix:utf8-encoding-windows" # recurring fixes
instinct observe "combo:pytest+coverage" # tool combinationsPattern prefixes are conventional, not magic: seq:, pref:, fix:, and
combo: keep the store searchable and easier to export. Add --cat <category>
to override the auto-inferred category if needed.
Tool Surface
A representative slice of the MCP tool surface; see the CLI Reference section below for the complete command list.
Tool / command | Use it for |
| Record or reinforce one pattern; repeats increment confidence. |
| Return mature patterns for current agent guidance. |
| Promote thresholds and run automatic chain detection. |
| End-of-session digest with recent observations and top suggestions. |
| Discover sequential patterns from confidence-log timestamps. |
| Measure which suggestions were reinforced by later observations. |
| Export rules for Claude, Cursor, Windsurf, Codex, or CLAUDE.md. |
| Decay stale patterns, find duplicates, clean orphan aliases, rebuild FTS. |
MCP Client Setup
Claude Code project-level .mcp.json:
{
"mcpServers": {
"instinct": {
"command": "instinct",
"args": ["serve"]
}
}
}Codex CLI:
[mcp_servers.instinct]
command = "instinct"
args = ["serve"]Cursor / Windsurf / HTTP clients:
{
"mcpServers": {
"instinct": {
"command": "instinct",
"args": ["serve", "--transport", "sse"]
}
}
}Server options:
instinct serve # stdio, default
instinct serve --transport sse # SSE
instinct serve --transport streamable-http # streamable HTTP
instinct serve --port 3777How It Compares
instinct is one of several memory layers for AI agents. The categories overlap, but
each project optimises for something different. This table is a head-to-head feature
matrix; raw adoption metrics, source URLs, and methodology live in
docs/comparison-benchmarks.md.
Project | Primary surface | Storage | Protocol | Confidence tiers / auto-promote | Cross-project promotion | Export targets | Setup friction |
| Coding-agent behavioural patterns (seq / pref / fix / combo) | Local SQLite WAL | MCP-native + CLI | Yes -- | Yes (universal tier) | Claude, Cursor, Windsurf, Codex, CLAUDE.md, Agent Skills |
|
General LLM memory (chat history, episodic facts) | Pluggable vector backend (Qdrant, pgvector, Chroma, ...) | Python / TS SDK + REST | No tier model; importance scoring | Via | SDK consumption (no flat-file export) | SDK + backend choice | |
Letta (formerly MemGPT) | Stateful agent runtime with built-in memory | Postgres / SQLite via runtime | Letta SDK + REST + MCP | Managed by agent (memory blocks) | Agent-level isolation | N/A (runtime, not exporter) | Server / Docker, framework-level |
Memory utilities for LangChain / LangGraph |
| LangChain SDK only | User-managed | Namespace-based | N/A (library) |
| |
Session capture + AI-compressed context re-injection | Local context files | Claude Code hooks + multi-tool | No tier model; full-session capture | Per-project session files | Context files for Claude / Codex / Copilot / Gemini / OpenCode |
| |
Persistent memory for coding agents (generic) | Local SQLite + FTS5 | MCP + HTTP + CLI + TUI | No (raw storage) | Per-project DB | Generic memory store | Single Go binary | |
ByteRover CLI (formerly Cipher) | Portable memory layer for autonomous coding agents | Local + cloud hybrid | MCP + CLI ( | Not advertised | Yes | Multi-agent compatible |
|
Developer snippets and workflow artefacts | Local Pieces OS + optional cloud | Proprietary SDK + IDE extensions | ML-tagged (not user-visible tier model) | Yes | IDE-native panels | Desktop app + IDE plugin | |
| Hand-written rule files | Flat text in repo | Loaded by the agent | Manual (you decide what's a rule) | Manual (you copy the file) | Itself a target format | Edit a file |
When to reach for instinct: your agent makes the same correction or follows the same workflow more than 3 times and you don't want to keep retyping. instinct records once, promotes after repetition, and surfaces the pattern back automatically through MCP.
Where instinct loses today (honest delta):
Adoption / maturity. instinct is new (April 2026, 2 GitHub stars at time of writing). Mem0, Letta, and claude-mem each have 5-6 figures of stars and years of iteration. If you need a battle-tested project with a large community, instinct is not it yet.
Chat-history recall. Mem0 stores episodic conversational facts and recalls them by query. instinct does not store conversation turns; it stores repeated behavioural patterns.
Full agent runtime. Letta gives you the whole agent loop (planner, memory, tools, state). instinct is a memory-only sidecar; you still bring your own agent.
LangChain-native integration. LangMem ships first-class
BaseStoreadapters and reducers for LangGraph. instinct is framework-agnostic via MCP, which costs you some LangChain-specific ergonomics.Session capture and replay. claude-mem snapshots and compresses entire Claude Code sessions for later context injection. instinct stores only the patterns the agent (or you) chose to
observe.Snippets and artefacts. Pieces stores code snippets, screenshots, and links. instinct stores patterns, not artefacts.
If any of those is your primary need, reach for the project that owns it. Reach for instinct when you want a small, local, MCP-native pattern store that promotes repeated behaviours into exportable rules.
Storage and Runtime
Package:
instinct-mcpPython:
>=3.11Runtime dependency:
mcp>=1.0.0Database: SQLite WAL at
~/.instinct/instinct.dbConfig: optional
~/.instinct/config.tomlCurrent release in this repo:
1.4.1
CLI Reference
instinct observe <pattern> # record/reinforce
instinct suggest # mature suggestions
instinct list # browse all patterns
instinct history <pattern> # confidence timeline
instinct effectiveness # suggestion confirmation rates
instinct export-platform codex # export for an agent/editor
instinct gc # decay + dedup + cleanup
instinct doctor # DB health checksAll core commands support --json where structured output is useful.
Recent Releases
1.4.1: repository transferred toWRG-11org + URL/metadata refresh (no behavioural changes).1.4.0: auto-chain detection and effectiveness scoring.1.3.0: platform export, MCP prompts, andgc.1.2.0: auto-promote on observe, confidence history, universal rules, CLAUDE.md import.1.1.0: Agent Skill export, CLAUDE.md injection, near-duplicate detection.
See CHANGELOG.md.
Repository Health
CI matrix: Python 3.11-3.14 on Ubuntu and Windows.
CodeQL security scanning on push and pull request.
Dependabot tracks GitHub Actions and pip updates weekly.
Published on PyPI, MCP Registry, and Glama.
License
Available Tools
23 toolsalias_patternA
Redirect all future observations of one pattern onto another.
Use this to merge duplicates: when the same concept has been recorded
under two keys (e.g. "seq:a->b" and "seq:a -> b" with a space), alias
the stray into the canonical one. Existing confidence is summed into
the target so no learning is lost.
The target must already exist. Use find_duplicates() to discover
merge candidates, then call this to apply them.
Args:
pattern: The key to retire. Future observations of this key will
be rerouted silently.
target: The canonical key to absorb into. Must already exist in
the store.
Returns:
On success: {"aliased": <pattern>, "target": <target>}.
On failure (target missing): {"error": "target pattern '<target>'
not found"} — check for the "error" key.
Inputs: pattern (required), target (required). Returns: object
consolidateA
Re-evaluate pattern levels; promote via confidence thresholds and detect chains.
Promotes patterns that crossed a level boundary since the last run:
raw -> mature (confidence >= 5), mature -> rule (>= 10), rule ->
universal (observed in 2+ distinct projects). Patterns seen in the
last 7 days get a +1 recency bonus toward the mature threshold.
Side effects: (1) writes new "promoted" values, (2) runs detect_chains()
to discover sequential patterns from the observation log, (3) rebuilds
the FTS5 search index. Idempotent across promotion: already-promoted
patterns are untouched. session_summary() invokes this automatically.
Call after a bulk import_patterns() / import_claude_md() or at the
end of an agent session so downstream queries (suggest,
export_rules, inject_claude_md) see the latest promotions.
Returns:
{"promoted_to_mature": int, "promoted_to_rule": int,
"promoted_to_universal": int, "chains_detected": int,
"chains_created": int, "total": int, "timestamp": iso8601}
"total" is the current row count after promotion. "chains_*"
fields reflect the bundled detect_chains() pass: "detected"
counts candidate pairs above threshold, "created" counts new
seq:A->B records actually inserted.
Inputs: no named parameters. Returns: object
detect_chainsA
Mine the observation log to auto-create "seq:A->B" patterns for recurring chains.
Scans the confidence log for pairs of patterns observed close in
time, and creates a new sequence pattern for any pair seen enough
times. This is how instinct learns tool chains without being told
what to track.
Safe to run periodically. Does not overwrite existing chains; only
appends confidence for new pairs.
Args:
window_minutes: Maximum gap between two observations to consider
them sequential. Smaller (1-2) = tight chains only. Larger
(10+) = loose associations. Default 5 is a good balance.
min_occurrences: Threshold for recording a chain. A pair must
appear at least this many times in the log before it becomes
a pattern. Default 3 filters out one-off coincidences.
Returns:
Dict with keys: "chains_created" (int — new patterns added),
"chains_reinforced" (int — existing patterns whose confidence
rose), "candidates_seen" (int — raw pair count before threshold).
Inputs: window_minutes, min_occurrences. Returns: object
effectivenessA
Measure how often suggested patterns were reinforced by a later observe().
Each suggest() call logs the patterns it returned; each observe()
confirms the most recent unconfirmed suggestion for that pattern.
A high confirmation rate means the pattern is genuinely useful
guidance; a low rate means it is noise worth pruning via
alias_pattern() merges or gc() decay. Read-only.
For a raw observation-velocity view use trending(days). For
promotion/level distribution use stats().
Args:
days: Look-back window in days. Default 30. Shorter (7)
surfaces recent drift; longer (90) measures long-term
value.
Returns:
{"patterns": [<row>, ...],
"summary": {"total_suggested": int, "total_confirmed": int,
"overall_rate": float, "period_days": int}}
Each <row>: {"pattern": str, "suggested": int,
"confirmed": int, "rate": float in [0.0, 1.0] rounded to
3 decimals}. Rows ordered by confirmed desc, then suggested
desc. "overall_rate" is total_confirmed / total_suggested
(0.0 when no suggestions in window). Empty "patterns" list
means no suggest() calls happened in the window — not an
error.
Inputs: days. Returns: object
export_claude_mdA
Render rule-level patterns as Markdown ready to paste into CLAUDE.md.
Use this when a Claude client needs a compact Markdown block of learned
rules to include manually in CLAUDE.md. It reads promoted rule-level
patterns only; no files are modified.
Produces one bullet per rule with pattern key, category tag, confidence
count, and explain text. The output is a freestanding Markdown section;
no surrounding headers or context are added.
For idempotent in-place injection into an existing CLAUDE.md (preserving
other content via marker tags), use inject_claude_md() instead.
For multi-platform output (Cursor, Windsurf, Codex), use
export_platform() instead.
Returns:
Dict with keys: "markdown" (str — the rendered block; empty
string if no rules exist), "rule_count" (int).
Inputs: no named parameters. Returns: object
export_platformA
Render rule-level patterns in a target editor's config format.
Use this when you want rules in a specific platform's rules file —
e.g. Cursor's .cursorrules, Windsurf's .windsurfrules, or Codex's
AGENTS.md — without hand-translating the output of export_rules().
Use fmt="claude-md" for the same Markdown renderer as
export_claude_md(); prefer export_claude_md() when you only need
Claude's CLAUDE.md shape.
For Anthropic-specific outputs (CLAUDE.md, SKILL.md), the dedicated
export_claude_md() and export_skill() tools keep the intent explicit.
Prefer this tool for non-Claude targets like .cursorrules,
.windsurfrules, or AGENTS.md.
Args:
fmt: Target platform. One of: "claude-md" (default),
"cursorrules", "windsurfrules", "codex". Unknown values are
rejected by validation instead of silently guessing.
Returns:
Dict with keys: "content" (str — formatted text ready to write
to disk; empty string when no rules exist), "format" (str —
echoed), "rule_count" (int).
Inputs: fmt. Returns: object
export_rulesA
Export promoted-level patterns (rule + universal) as structured JSON.
Filters to patterns with promoted >= 2 — the threshold set by
consolidate() after enough reinforcement. Intended for programmatic
consumption: analytics pipelines, sibling agents, external
dashboards. Read-only; takes no parameters.
For human-readable Markdown use export_claude_md(). For platform-
specific formats use export_platform() (.cursorrules, .windsurf,
AGENTS.md) or export_skill() (anthropics/skills SKILL.md). For
lower-confidence audits use list_instincts(min_confidence=5).
Returns:
{"rules": [<record>, ...], "count": int, "hint": str}
Each <record> has: "pattern" (str key with prefix),
"category" ("sequence"|"preference"|"fix_pattern"|"combo"),
"confidence" (int observation count),
"promoted" (2=rule, 3=universal — lower levels are filtered out),
"level" ("rule"|"universal"),
"project" (str fingerprint, "" = global),
"source" (str origin tag), "metadata" (parsed dict),
"explain" (str human note),
"first_seen" and "last_seen" (ISO 8601 timestamps).
Sorted by promoted descending, then confidence descending.
Empty "rules" means no pattern has reached rule level yet —
the "hint" directs to run consolidate() first, then retry.
Inputs: no named parameters. Returns: object
export_skillA
Package rule-level patterns as a SKILL.md file (anthropics/skills format).
Builds a complete Skill document: YAML frontmatter (name,
description) followed by a Markdown body grouping each rule-level
pattern by category, with confidence and explain text. The returned
string is ready to write to disk as SKILL.md and install into a
skills-aware agent runtime (e.g. agentskills.io). Read-only.
For human-readable CLAUDE.md output use export_claude_md(). For
editor-specific formats (.cursorrules, AGENTS.md) use
export_platform(target). For raw JSON use export_rules().
Args:
name: Skill identifier written into the YAML frontmatter.
Becomes the Skill's name on disk. Default "instinct-rules".
description: One-sentence description in the frontmatter.
Empty string auto-generates "Learned patterns from N
observations" using the current rule count.
category: Filter rules by type. One of "sequence",
"preference", "fix_pattern", "combo". Empty string (default)
includes every category.
Returns:
On success: {"skill_md": str, "rule_count": int, "hint": str}.
"skill_md" is the full file content ready to write. "rule_count"
is parsed from the rendered body (number of rule bullets).
On empty store: {"skill_md": "", "rule_count": 0, "hint": str}.
"hint" explains the promoted >= 2 prerequisite and directs the
caller to run consolidate() first so mature patterns can cross
the threshold.
Inputs: name, description, category. Returns: object
find_duplicatesA
Detect near-identical pattern keys that should probably be merged.
Compares every pattern against every other using token overlap and
prefix matching. Flags candidate pairs above the threshold so you
can apply alias_pattern() to consolidate them. Read-only — this
tool suggests merges but never performs them.
A common use case: after a bulk import_patterns() or import_claude_md(),
call this to catch formatting drift (spacing, casing, punctuation).
Args:
threshold: Similarity cutoff, 0.0 to 1.0. Default 0.75. Lower
thresholds (0.5) over-suggest; higher (0.9) under-suggest.
Start at default and tune per your noise tolerance.
Returns:
Dict with keys: "duplicates" (list of {pattern_a, pattern_b,
similarity}), "count" (int), "hint" pointing to alias_pattern
as the next step.
Inputs: threshold. Returns: object
gcA
Run all store-maintenance tasks in one call: decay, dedup, orphans, FTS.
Combines four housekeeping steps:
1. Decay confidence on patterns idle beyond the staleness threshold.
2. Merge near-duplicates using the given similarity threshold.
3. Remove alias entries whose target no longer exists.
4. Rebuild the SQLite FTS index for accurate search results.
Safe and idempotent — running more than once per day is fine. For
finer control, the individual steps are available as find_duplicates()
+ alias_pattern() + (internal) decay.
Args:
dedup_threshold: Similarity cutoff for step 2, 0.0-1.0. Default
0.75. See find_duplicates() for tuning notes.
Returns:
Dict with keys: "decay" (dict with "decayed" and "deleted"),
"dedup" (dict with "found" and "applied"), "orphans_cleaned"
(int), "fts_rebuilt" (bool).
Prefer housekeep() for discoverability; gc() remains supported for
existing clients.
Inputs: dedup_threshold. Returns: object
get_instinctA
Fetch the full record for one pattern by its exact key.
Exact-match lookup; keys are case-sensitive and must include the
category prefix. Typically called after suggest() returns a compact
entry and you want the full context. Read-only.
For substring or keyword search use search_instincts(). For browsing
by category/project without a key use list_instincts(). For the
confidence timeline of this pattern, pair with history(pattern).
Args:
pattern: Exact pattern key including its category prefix.
Examples: "seq:lint->fix->lint", "pref:style=black",
"fix:null-deref-guard", "combo:eslint+prettier". Case-sensitive.
Returns:
On hit — the full record: {"pattern": str, "category":
"sequence"|"preference"|"fix_pattern"|"combo", "confidence": int,
"promoted": 0|1|2|3, "level": "raw"|"mature"|"rule"|"universal",
"project": str ("" = global), "source": str, "metadata": dict,
"explain": str, "first_seen": iso8601, "last_seen": iso8601}.
On miss — {"error": "Not found: <pattern>"}. Callers must check
for the "error" key before assuming a record was returned.
Inputs: pattern (required). Returns: object
historyA
Show how one pattern's confidence evolved over a time window.
Returns every observation recorded against the pattern in the window,
with timestamps and source projects — useful for spotting growth
velocity, cross-project adoption, or stale patterns that should decay.
For a snapshot of the current state (not the timeline), use
get_instinct() instead.
Args:
pattern: Exact pattern key. Same format as get_instinct() —
case-sensitive, includes prefix (e.g. "seq:lint->fix").
days: Look-back window in days. Default 30.
Returns:
Dict with keys: "pattern" (str — echoed), "history" (list of
{timestamp, source, project, delta}), "data_points" (int),
"projects" (list of distinct project fingerprints seen).
Inputs: pattern (required), days. Returns: object
housekeepA
Run cleanup, deduplication, decay, orphan cleanup, and FTS rebuild.
Use this when you want to "clean up", "housekeep", "prune stale
patterns", or "rebuild search" after many observations or imports.
This is the natural-language alias for gc(); both tools are identical
and safe to run periodically.
Args:
dedup_threshold: Similarity cutoff for duplicate merging,
0.0-1.0. Default 0.75. See find_duplicates() for tuning notes.
Returns:
Dict with keys: "decay" (dict with "decayed" and "deleted"),
"dedup" (dict with "found" and "applied"), "orphans_cleaned"
(int), "fts_rebuilt" (bool).
Inputs: dedup_threshold. Returns: object
import_claude_mdA
Parse a CLAUDE.md file and ingest its backtick-wrapped patterns.
Scans the file for patterns matching the instinct convention
(seq:..., pref:..., fix:..., combo:...) and imports each as an
observation. Extracts confidence counts and explain text when
present on the line.
Use this to bootstrap a fresh instinct store from an existing
project's CLAUDE.md, or to sync rules authored by hand.
Args:
source: Path to the CLAUDE.md file. Read-only — the source
file is not modified.
Returns:
Dict with keys: "imported" (int — new patterns), "merged"
(int — reinforced existing patterns), "skipped" (int — lines
that looked pattern-like but failed validation), "source" (str).
Inputs: source (required). Returns: object
import_patternsA
Bulk-insert many patterns in a single call; faster than looping observe().
Each input row is routed through observe() so existing patterns
have their confidence incremented rather than overwritten, matching
single-call observe() semantics. If an input row specifies a
"confidence" higher than the current stored value, the record is
raised to that target value (never lowered). Rows with missing or
empty "pattern" are skipped.
For importing a CLAUDE.md Markdown file use import_claude_md()
which handles the backtick-wrapped pattern parsing for you. Run
consolidate() after a large import so downstream exports see the
fresh promotions.
Args:
patterns: List of dicts. Each dict requires "pattern" (str key
with category prefix). Optional keys:
- "category": "sequence" | "preference" | "fix_pattern"
| "combo". Defaults to "sequence" if omitted.
- "source": str origin tag (e.g. "codex", "manual").
- "project": str fingerprint. Empty = global.
- "metadata": dict of free-form JSON-serializable data.
- "explain": str human-readable note (truncated at the
store-configured max length).
- "confidence": int starting count. Defaults to 1. If
greater than the current stored confidence for a
pre-existing pattern, the record is raised to this
value.
Returns:
{"imported": int, "updated": int, "errors": int, "hint": str}
"imported" = rows that created a new pattern. "updated" =
rows that reinforced an existing pattern. "errors" = rows
skipped because "pattern" was missing/empty or observe() raised
(count only — see server logs for per-row reasons). "hint"
points to consolidate() as the recommended follow-up.
Inputs: patterns (required). Returns: object
inject_claude_mdA
Idempotently write rule-level patterns into a CLAUDE.md file.
Updates only the block between <!-- instinct:start --> and
<!-- instinct:end --> markers; everything else in the file is
preserved. Creates the file (and markers) if they do not exist.
Safe to run on every commit or session end without producing churn.
For one-shot rendering without touching the filesystem, use
export_claude_md() and write the output yourself.
Args:
target: Absolute or relative path to the CLAUDE.md file. Parent
directories must exist; the file itself will be created.
Returns:
Dict with keys: "target" (str — echoed path), "rule_count"
(int), "changed" (bool — false when content matched existing
block, true when the file was actually rewritten).
Inputs: target (required). Returns: object
list_instinctsA
List recorded patterns with optional filters; includes low-confidence observations.
Unlike suggest() — which returns mature-only, compact payloads — this
surfaces seedlings too. Useful for audits, pruning noise via gc() or
alias_pattern(), and debugging why a pattern has not promoted.
Read-only; records sorted by confidence descending, then last_seen
descending.
For day-to-day agent guidance prefer suggest(). For keyword search
use search_instincts(). For a single exact-key lookup use
get_instinct().
Args:
min_confidence: Minimum observation count (inclusive). Examples:
1 returns everything including one-offs; 5 returns mature+;
10 returns rules only.
category: Filter by pattern type. One of: "sequence",
"preference", "fix_pattern", "combo". Empty string = all.
project: Filter by project fingerprint (repo hash or path hash).
Empty string returns every project including the global ""
bucket.
limit: Maximum records to return. Default 50; raise for full
dumps, lower for top-N views.
Returns:
{"instincts": [<record>, ...], "count": int, "hint": str}
Each <record> has: "pattern" (str key with prefix),
"category" ("sequence"|"preference"|"fix_pattern"|"combo"),
"confidence" (int observation count),
"promoted" (0=raw, 1=mature, 2=rule, 3=universal),
"level" ("raw"|"mature"|"rule"|"universal" — string form of promoted),
"project" (str fingerprint, "" = global),
"source" (str origin tag), "metadata" (parsed dict),
"explain" (str human-readable note),
"first_seen" and "last_seen" (ISO 8601 timestamps).
"hint" points to suggest() / search_instincts() / get_instinct()
as next-step tools depending on the audit goal.
Inputs: min_confidence, category, project, limit. Returns: object
observeA
Record one observation of a behavioral pattern; increments its confidence counter.
Use this to log anything you want the agent to learn over time: a tool
sequence that worked, a user preference, a recurring fix, or a combo
of tools used together. Call once per occurrence — repeated calls on
the same pattern raise its confidence (1=new, 5=mature, 10=rule).
Do NOT use this for one-off notes; those belong in regular memory.
This tool is for patterns that may recur and become reliable.
Idempotent on pattern key: same pattern string merges into one entry.
Args:
pattern: Pattern key following the convention prefix:body.
Examples: "seq:lint->fix->lint" (tool sequence),
"pref:style=black" (user preference),
"fix:missing-import" (recurring fix),
"combo:pytest+coverage" (things used together).
category: Pattern type. One of: "sequence", "preference",
"fix_pattern", "combo". Defaults to "sequence".
source: Originating tool/agent name (e.g. "claude-code",
"cursor"). Empty string means unknown. Useful for filtering.
project: Project fingerprint. Empty string auto-detects from cwd
(recommended). Pass explicitly only for cross-project imports.
explain: One-line human-readable rationale for why this pattern
matters. Surfaces in suggestions and CLAUDE.md exports.
Returns:
Dict with keys: "pattern", "confidence" (int), "level"
("seedling" | "mature" | "rule"), "created" (bool — true on
first observation).
Inputs: pattern (required), category, source, project, +1 more. Returns: object
search_instinctsA
Find patterns by keyword across pattern key, metadata, and explain text.
Uses SQLite FTS5 for ranked, fast retrieval. Falls back to LIKE
substring matching automatically when the query contains special
characters that FTS5 cannot tokenize. Read-only; no side effects.
FTS5 query syntax:
- Bare word "lint" — matches any record containing the token.
- Multi-word "lint fix" — implicit AND; both tokens must appear.
- Explicit "lint OR format" — either token.
- Phrase '"exact phrase"' — contiguous match (note embedded quotes).
- Prefix "claude*" — any token starting with claude.
- Negation "lint NOT prettier" — excludes matches containing the
second term.
For exact-key lookup use get_instinct(). For unfiltered browsing or
category/project filters without a keyword, use list_instincts().
Args:
query: Search term in FTS5 syntax (see above). Case-insensitive.
Special characters trigger automatic LIKE fallback.
limit: Maximum results to return. Default 20; raise for broad
audits, lower for suggest-like focused views.
Returns:
{"results": [<record>, ...], "count": int, "hint": str}
Each <record> has: "pattern" (str key with prefix),
"category" ("sequence"|"preference"|"fix_pattern"|"combo"),
"confidence" (int observation count),
"promoted" (0=raw, 1=mature, 2=rule, 3=universal),
"level" ("raw"|"mature"|"rule"|"universal"),
"project" (str fingerprint, "" = global),
"source" (str origin tag), "metadata" (parsed dict),
"explain" (str human note),
"first_seen" and "last_seen" (ISO 8601 timestamps).
Ordered by confidence descending. Empty "results" means no match;
the "hint" points to list_instincts() or get_instinct() as
fallback next steps.
Inputs: query (required), limit. Returns: object
session_summaryA
End-of-session snapshot: what was learned, what's mature, and housekeeping.
Call this at the end of an agent session to get a one-call overview
suitable for a session log or memory append: recent activity (last
24h), top mature suggestions, and overall store stats.
Side effect: also runs consolidate() and rebuilds the FTS search
index. If you want a pure read-only summary, use stats() + suggest()
separately.
Args:
project: Project fingerprint to scope the summary. Empty string
auto-detects from cwd (recommended).
Returns:
Dict with keys: "session" (patterns_last_24h + recent list of
up to 10), "suggestions" (count + top 5 by confidence),
"stats" (full stats() payload), "consolidation"
(promotion counts from the consolidate() call).
Inputs: project. Returns: object
statsA
Summary of the instinct store: totals, level distribution, category breakdown.
Use for a quick health check — how many patterns exist, how they
are distributed across promotion levels, which categories dominate,
and the average/peak confidence. Read-only; no side effects; no
params.
For a time-ranged view of what's been observed recently use
trending(days). For end-of-session snapshot that also runs
consolidate use session_summary().
Returns:
{"total": int, "raw": int, "mature": int, "rules": int,
"universal": int, "avg_confidence": float, "max_confidence": int,
"by_category": {<category>: {"count": int,
"avg_confidence": float}}}
Level counts partition "total": raw + mature + rules +
universal == total. "by_category" keys are a subset of
("sequence", "preference", "fix_pattern", "combo") — only
categories actually present appear as keys. Empty store returns
zero counts everywhere, not an error.
Inputs: no named parameters. Returns: object
suggestA
Retrieve mature patterns (confidence >= 5) to guide your current behavior.
Call this at the start of a task to learn how similar work has been
handled before: which tool sequences worked, what the user prefers,
which fixes recur. Results are sorted by confidence descending, so
the most-trusted patterns come first.
Prefer this over list_instincts when you want only validated patterns
(not every observation). Use list_instincts to see seedlings too.
Args:
project: Filter by project fingerprint. Empty string returns the
current project's patterns plus global ones. Pass a specific
fingerprint to audit another project.
category: Filter by pattern type. One of: "sequence", "preference",
"fix_pattern", "combo". Empty string returns all categories.
keyword: Substring match against pattern key, metadata, and
explain text. Case-insensitive. Empty string disables filter.
compact: True (default) returns ~50 tokens per pattern (key +
confidence + level only) — ideal for agent context. False
returns full metadata and explain text (~500 tokens each) —
use for audits or UI display.
Returns:
Dict with keys: "suggestions" (list of patterns, compact or
full depending on flag), "count" (int), and in compact mode a
"hint" pointing to get_instinct for details.
Inputs: project, category, keyword, compact. Returns: object
trendingA
Rank patterns by observation velocity (reinforcements per window).
Counts entries in the confidence log per pattern within the window
and returns the busiest. A brand-new pattern observed 10 times
today outranks a long-mature pattern idle for weeks. Falls back to
last_seen ordering for patterns with no log entries (pre-history
data). Read-only.
For all-time leaderboards use list_instincts(min_confidence=10).
For the confirmation-rate view of whether trending patterns were
actually useful, pair with effectiveness(days).
Args:
days: Window size in days. Default 7. Smaller (1) = what is
hot right now; larger (30) = what is steady over the
month.
limit: Max patterns to return. Default 10, ordered by window
observation count descending.
Returns:
{"trending": [<record>, ...], "period_days": int}
Each <record> is a full pattern record (see list_instincts
for field list) augmented with an extra field
"observations_in_period": int — the number of reinforcements
counted in this window. When the fallback path runs (no log
history), this field is absent; ordering is then by
"confidence" and "last_seen" descending.
"period_days" echoes the input so callers can cache results
against a window size.
Inputs: days, limit. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
The export family overlaps (export_claude_md vs export_platform with fmt=claude-md) and gc/housekeep are explicitly identical maintenance tools, creating real boundary confusion. Most read/search tools are well cross-referenced, but the near-duplicates and the side-effectful session_summary muddle the overall set.
The dominant verb_noun pattern (list_instincts, export_rules, import_patterns) is clear, but the set mixes bare verbs (observe, suggest, consolidate), nouns (stats, history, trending, effectiveness), and an acronym (gc) with a full alias (housekeep). This is not chaotic, but it prevents reliable name prediction.
23 tools is heavy for a pattern-store domain, sitting at the upper bound of the borderline range. Many tools are variations of the same concern: five export/render tools, two identical maintenance tools, and three list/search variants, so the count feels inflated rather than a necessary feature set.
The lifecycle is well covered: observe/import creates, list/get/search reads, consolidate promotes, export/inject distributes, and gc/housekeep maintains. The main gap is no explicit targeted delete/forget tool for individual patterns, since gc and alias_pattern are the only removal paths.
Maintenance
Related MCP Connectors
Memory, reflection and safety for AI agents. Hosted or local, no vector database.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Shared control plane for AI coding agents — tasks, memory, decisions, file locks. 12 tools.
Shared project memory for coding agents: decisions, lessons, guardrails and tasks per repository.