| 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).
|
| 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.
|
| list_instinctsA | List every recorded pattern (including seedlings), optionally filtered. Use this for audits, debugging, or when you want to see patterns that
have not yet matured. Unlike suggest(), this returns low-confidence
observations too, which is useful for pruning noise with gc() or
alias_pattern().
For day-to-day agent guidance, prefer suggest() — it filters to
confidence >= 5 automatically and returns a more compact payload.
Args:
min_confidence: Minimum observation count required (inclusive).
1 (default) returns everything including one-offs. Pass 5
for matures only, 10 for rules only.
category: Filter by pattern type. One of: "sequence",
"preference", "fix_pattern", "combo". Empty string = all.
project: Filter by project fingerprint. Empty string = all
projects (global view).
Returns:
Dict with keys: "instincts" (list of full pattern records with
metadata, explain, timestamps), "count" (int).
|
| get_instinctA | Fetch the full record for one pattern by its exact key. Use this to inspect a single pattern's confidence, level, source,
project, metadata, explain text, and timestamps — typically after
suggest() returns a compact entry and you want the full context.
This is an exact-match lookup. For substring or keyword search,
use search_instincts() instead.
Args:
pattern: Exact pattern key including its prefix (e.g.
"seq:lint->fix->lint", "pref:style=black"). Case-sensitive.
Returns:
Dict with the full pattern record (pattern, confidence, level,
category, source, project, metadata, explain, first_seen,
last_seen). If the pattern does not exist, returns
{"error": "Not found: <pattern>"} — check for the "error" key.
|
| consolidateA | Re-evaluate every pattern's level based on current confidence. Promotes patterns that crossed a threshold since last run: seedling
(<5) -> mature (>=5) -> rule (>=10). Idempotent — safe to call
repeatedly; patterns already at the correct level are untouched.
Call at session end, or after a bulk import, so downstream queries
(suggest, export_rules, CLAUDE.md injection) reflect the latest
promotions. session_summary() calls this automatically.
Returns:
Dict with keys: "promoted_to_mature" (int), "promoted_to_rule"
(int), "demoted" (int — only non-zero if decay is enabled),
"total_checked" (int).
|
| statsA | Summarize the instinct store: counts, levels, categories, projects. Use this for a quick health check — how many patterns exist, how
many have matured, which categories dominate, which projects have
the most learning. Read-only; no side effects.
Returns:
Dict with keys: "total" (int), "by_level" ({seedling, mature,
rule}), "by_category" ({sequence, preference, fix_pattern,
combo}), "by_project" (dict of fingerprint -> count), "oldest"
and "newest" ISO timestamps.
|
| search_instinctsA | Find patterns whose key, metadata, or explain text contains the query. Use this when you remember roughly what a pattern was about but not
the exact key — searches across pattern name, stored metadata, and
the human-readable explain field. Case-insensitive substring match
(backed by SQLite FTS for speed).
For exact-key lookup use get_instinct(). For browsing by category
or project without a keyword, use list_instincts().
Args:
query: Search term. Can be a partial pattern key ("lint"),
a metadata value, or explain text. Multi-word queries match
any word (OR semantics).
Returns:
Dict with keys: "results" (list of matching pattern records,
ordered by confidence desc), "count" (int).
|
| export_rulesA | Export rule-level patterns (confidence >= 10) as structured JSON. Use this to hand off validated instincts to another system — an
analytics pipeline, a dashboard, or a sibling agent. Returns the
raw records without any formatting.
For human-readable or platform-specific output (CLAUDE.md,
.cursorrules, SKILL.md), use export_claude_md(), export_platform(),
or export_skill() instead.
Returns:
Dict with keys: "rules" (list of pattern records with full
metadata), "count" (int). Empty list if no patterns have
reached rule level yet.
|
| alias_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.
|
| import_patternsA | Bulk-insert many patterns in a single call; faster than looping observe(). Use this to seed the store from an external source — a CSV export,
another project's instinct DB, or patterns extracted by a script.
For patterns already present, confidence is summed (not replaced),
matching observe() semantics.
For importing from a CLAUDE.md file specifically, prefer
import_claude_md() which handles the markdown parsing for you.
Args:
patterns: List of dicts. Each dict requires at minimum a
"pattern" key. Optional keys: "category" (sequence |
preference | fix_pattern | combo), "source", "project",
"metadata" (dict), "explain" (str), "confidence" (int —
starting count, defaults to 1).
Returns:
Dict with keys: "imported" (int — new patterns created),
"merged" (int — existing patterns whose confidence rose),
"errors" (list of {"pattern", "reason"} for rejected rows).
|
| 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).
|
| 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).
|
| effectivenessA | Measure how often suggested patterns actually got used afterwards. For each pattern returned by suggest() in the window, checks whether
it was observed again later. A high confirmation rate means the
pattern is genuinely useful guidance; a low rate means it is noise
that should be pruned.
Use this to tune your store — patterns below a threshold may belong
in alias_pattern() merges or gc() decay.
Args:
days: Look-back window in days. Default 30. Shorter windows
surface recent drift; longer windows measure long-term value.
Returns:
Dict with keys: "window_days" (int), "patterns" (list of
{pattern, suggested_count, confirmed_count, rate}), "overall_rate"
(float 0.0-1.0 across all patterns).
|
| trendingA | Rank patterns by observation velocity in a recent window. Use this to surface what the agent is currently learning about: the
patterns that have accumulated the most observations in the last N
days, regardless of total confidence. A brand-new pattern observed
10 times today outranks a long-mature pattern idle for weeks.
For all-time leaderboards use list_instincts(min_confidence=10);
for recent activity use this.
Args:
days: Window size in days. Default 7. Smaller = what's hot now;
larger = what's been steady.
limit: Max patterns to return, sorted by observation count
descending. Default 10.
Returns:
Dict with keys: "trending" (list of {pattern, observations,
confidence, level}), "period_days" (int, echoes input).
|
| export_claude_mdA | Render rule-level patterns as Markdown ready to paste into CLAUDE.md. 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.
Returns:
Dict with keys: "markdown" (str — the rendered block; empty
string if no rules exist), "rule_count" (int).
|
| export_skillA | Package rule-level patterns as a SKILL.md file (Anthropic Agent Skill format). Use this to turn learned instincts into a distributable Skill that
other agents can install — compatible with the anthropics/skills
standard. The output includes YAML frontmatter plus a body of rules
grouped by category.
For raw CLAUDE.md output instead of the Skill format, use
export_claude_md(). For other editors (.cursorrules etc.), use
export_platform().
Args:
name: Skill name for the YAML frontmatter. Becomes the Skill's
identifier. Default "instinct-rules".
description: One-sentence description in frontmatter. Empty
string auto-generates "Learned patterns from N observations".
category: Filter rules by type ("sequence", "preference",
"fix_pattern", "combo"). Empty string includes all categories.
Returns:
Dict with keys: "skill_md" (str — full SKILL.md content ready
to write to disk; empty string if no rules yet), "rule_count"
(int), and on empty a "hint" explaining the >=10 threshold.
|
| 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).
|
| 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.
|
| 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).
|
| 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).
|
| 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().
For Anthropic-specific outputs (CLAUDE.md, SKILL.md), the dedicated
export_claude_md() and export_skill() tools include richer formatting.
Args:
fmt: Target platform. One of: "claude-md" (default),
"cursorrules", "windsurfrules", "codex". Unknown values
return an empty content string.
Returns:
Dict with keys: "content" (str — formatted text ready to write
to disk), "format" (str — echoed), "rule_count" (int).
|
| 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: "decayed" (int), "merged" (int), "orphans_removed"
(int), "fts_rebuilt" (bool).
|
