# Capy Cortex

Autonomous learning system that learns from mistakes and reflects on sessions to get smarter over time

[Source: niveshdandyan](https://github.com/happycapy-ai/Happycapy-skills/tree/main/skills/capy-cortex)

## Capy Cortex

Capy Cortex is a foundational skill for AI assistants that need to build persistent, self-improving knowledge systems capable of learning from past interactions and retrieving contextually relevant information during live sessions.

## What Is Capy Cortex

Capy Cortex is an autonomous learning system that combines SQLite storage, FTS5 full-text search, and scikit-learn TF-IDF vectorization into a unified memory and retrieval engine. It gives your AI assistant the ability to remember mistakes, extract preferences, consolidate repeated observations into durable principles, and surface relevant knowledge at the right moment.

The system operates through several interconnected components. A hook-based learning mechanism captures errors and corrections as they occur. A reflection engine processes completed sessions to extract patterns and insights. A consolidation pipeline merges related rules into higher-level principles over time. A two-stage retrieval system first uses FTS5 for fast candidate selection, then re-ranks results using TF-IDF cosine similarity for precision.

Anti-pattern recording ensures that known failure modes are stored and flagged during future interactions. Confidence decay gradually reduces the weight of older, unvalidated knowledge, keeping the system accurate and current.

## Why Use Capy Cortex

Most AI assistants operate statelessly, repeating the same mistakes across sessions because they have no mechanism for retaining and applying learned knowledge. Capy Cortex solves this directly.

By persisting knowledge in SQLite with FTS5 indexing, retrieval remains fast even as the knowledge base grows to thousands of entries. TF-IDF re-ranking ensures that the most semantically relevant results appear first, not just the most recently stored ones. Confidence decay prevents outdated rules from polluting current reasoning, while the consolidation pipeline reduces noise by merging redundant entries into concise principles.

The result is an assistant that improves measurably over time, avoids repeating documented anti-patterns, and adapts its behavior to match extracted user preferences.

## How to Use Capy Cortex

Invoke the skill using the `capy-cortex` skill ID. The primary operations are `learn`, `reflect`, `retrieve`, and `consolidate`.

To record a mistake and store a corrective rule:

```python
capy_cortex.learn(
    event_type="mistake",
    content="Used append() inside a loop to build large lists",
    correction="Use list comprehensions or pre-allocated arrays for performance",
    confidence=0.9,
    tags=["python", "performance", "anti-pattern"]
)
```

To retrieve relevant knowledge before responding to a user query:

```python
results = capy_cortex.retrieve(
    query="python list performance optimization",
    top_k=5,
    rerank=True
)
for entry in results:
    print(entry.content, entry.confidence_score)
```

The `rerank=True` flag activates the two-stage FTS5 plus TF-IDF pipeline. Without it, only FTS5 results are returned, which is faster but less precise.

To trigger session reflection after a completed interaction:

```python
capy_cortex.reflect(
    session_id="session_20240815",
    depth="deep",
    extract_preferences=True,
    consolidate_threshold=3
)
```

The `consolidate_threshold=3` parameter means that any pattern observed three or more times during the session will be promoted to a consolidated principle automatically.

To run a manual consolidation pass across the full knowledge base:

```python
capy_cortex.consolidate(
    min_occurrences=5,
    similarity_threshold=0.82,
    decay_factor=0.95
)
```

This merges entries with cosine similarity above 0.82, applies a 0.95 confidence decay multiplier to all entries not reinforced recently, and removes entries whose confidence has fallen below 0.1.

## When to Use Capy Cortex

Use Capy Cortex in any deployment where the assistant handles repeated interactions with the same user or domain. It is particularly valuable in coding assistants, where anti-pattern avoidance and preference tracking produce measurable quality improvements over time.

Trigger `retrieve` at the start of each response generation cycle to prime the assistant with relevant prior knowledge. Trigger `learn` immediately after any user correction or explicit feedback. Schedule `reflect` at the end of each session or after a defined interaction count. Run `consolidate` on a periodic basis, such as daily or after every fifty sessions, to maintain knowledge base quality.

Avoid calling `consolidate` during active sessions, as it performs full-table scans and TF-IDF re-vectorization, which introduces latency.

## Important Notes

The FTS5 index requires SQLite version 3.9.0 or higher. Verify this before deployment. TF-IDF vectorization uses scikit-learn's `TfidfVectorizer` with default tokenization, so domain-specific terminology may require a custom analyzer passed via the `vectorizer_config` parameter. Confidence scores must remain between 0.0 and 1.0. Entries stored with a confidence below 0.3 are excluded from retrieval by default but remain in storage for audit purposes.

The hook-based architecture means that most learning happens automatically without explicit invocation. The `SessionStart` hook loads anti-patterns and preferences into context. The `UserPromptSubmit` hook retrieves task-relevant rules using FTS5. The `PostToolUseFailure` hook records errors as new anti-patterns. The `Stop` hook extracts corrections and preferences from the completed conversation. This passive learning pipeline ensures continuous improvement with zero manual overhead from the user.