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:

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:

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:

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:

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.

FAQ

Q: How does Capy Cortex help my AI agent learn from mistakes?

Capy Cortex enables your AI agent to analyze errors during sessions and adapt its behavior for improved future performance. This autonomous learning process is a core feature of the Skills platform.

Q: Can Capy Cortex be used with other Happycapy Skills?

Yes, Capy Cortex is designed to integrate seamlessly with other Happycapy Skills, enhancing the overall intelligence and adaptability of your AI agent.

Q: Does Capy Cortex require manual configuration to reflect on sessions?

No, Capy Cortex automatically reflects on each session to identify areas for improvement. This feature allows the AI agent to become smarter over time without manual intervention.

Q: What makes Capy Cortex different from other learning Skills on Happycapy?

Capy Cortex stands out by focusing on autonomous mistake-driven learning and session reflection, allowing AI agents to continuously evolve within the Happycapy ecosystem.

Q: Where can I find the source code for Capy Cortex on the Skills platform?

The source code for Capy Cortex is available on the official Happycapy Skills GitHub repository, making it easy to review, customize, or contribute to the project.