Memory Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• packages/core/src/memory/injector.ts
• packages/core/src/memory/memory-index.ts
• packages/core/src/memory/initializer.ts
• packages/cli/src/commands/memory.ts
• packages/core/src/memory/tests/injector.test.ts

The Memory Architecture in SkillKit is a multi-layered system designed to capture, store, and inject context-aware "learnings" into various AI coding agents. It facilitates session persistence by recording observations from coding interactions and compressing them into long-term memories that can be retrieved based on relevance to the current task, project stack, or specific tags.

This architecture operates across two primary scopes: Project (local to a specific repository) and Global (available across all projects on a user's machine). By maintaining these separate stores, the system ensures that project-specific conventions are preserved while general best practices are shared globally.

Sources: packages/core/src/memory/injector.ts:65-72, packages/cli/src/commands/memory.ts:140-160

Core Storage Components

The memory system relies on a structured directory and file layout to manage observations, learnings, and search indices.

Memory File Structure

The system uses the .skillkit/memory directory within projects and a corresponding directory in the user's home folder for global data.

File Path	Description
observations.yaml	Raw session data captured during active agent interactions.
learnings.yaml	Compressed, long-term memories derived from observations.
index.yaml	Search index mapping keywords and tags to specific learning IDs.
global.yaml	Shared learnings available across all local projects.

Sources: packages/core/src/memory/initializer.ts:16-24, packages/core/src/memory/memory-index.ts:12-18

The Memory Index

The MemoryIndexStore manages a reverse-index of learnings. It extracts keywords from titles and content while ignoring common "stop words" to facilitate fast retrieval.

The indexing process ensures that frameworks (e.g., React, Next.js) and custom tags are treated as first-class search citizens.
Sources: packages/core/src/memory/memory-index.ts:46-85

Memory Injection Pipeline

The MemoryInjector is responsible for selecting the most relevant memories and formatting them for specific AI agents (e.g., Claude, Cursor, Copilot).

Relevance Scoring Logic

Memories are scored on a scale of 0-100 based on several weighted factors:

1. Framework Match (+15 per match): Compares the memory's metadata against the detected project stack.
2. Requested Tags (+20 per match): High priority for tags explicitly requested by the user or agent.
3. Keyword Match (+10 per match): Textual similarity between the current task description and memory content.
4. Recency & Popularity: Boosts scores for memories used frequently (+2 per use) or updated within the last 7-30 days (+5 to +10).

Sources: packages/core/src/memory/injector.ts:105-165

Agent-Specific Formatting

Once selected, memories are formatted into the native configuration styles of the target agent to ensure they are interpreted correctly as context.

Agent	Format Style	Implementation
Claude Code	XML Tags	Wraps memories in <memories> and <memory> tags.
Cursor	.mdc / Markdown	Uses YAML frontmatter with globs and alwaysApply.
Copilot	Markdown Comments	Uses <!-- Session Memories --> to hide context from the user.

Sources: packages/core/src/memory/injector.ts:258-335

Data Flow: Observation to Learning

The transition from raw data to permanent memory involves a compression phase where transient observations are consolidated into "Learnings."

Command Line Interface (CLI)

The MemoryCommand provides the primary interface for users to manage the lifecycle of their coding memories.

Key CLI Actions

• status: Displays counts for session observations and project/global learnings.
• search: Queries the MemoryIndexStore using keywords or tags.
• compress: Invokes the compressor to turn raw observations into learnings.
• export: Converts a specific learning into a standalone SKILL.md file.
• rate: Manually adjusts the effectiveness score of a learning (0-100).

Sources: packages/cli/src/commands/memory.ts:40-60, packages/cli/src/commands/memory.ts:140-160

Implementation Details

Data Structures

The InjectedMemory interface represents a memory that has been processed and scored for a specific context.

export interface InjectedMemory {
  learning: Learning;
  relevanceScore: number;
  matchedBy: {
    frameworks: string[];
    tags: string[];
    keywords: string[];
    patterns: string[];
  };
  tokenEstimate: number;
}

Sources: packages/core/src/memory/injector.ts:44-55

Token Budgeting

To avoid overwhelming agent context windows, the MemoryInjector estimates tokens (approx. 0.25 tokens per character) and truncates results based on a maxTokens budget (default: 2000).

Sources: packages/core/src/memory/injector.ts:57-61, packages/core/src/memory/injector.ts:195-215

Conclusion

The SkillKit Memory Architecture provides a robust framework for cross-agent knowledge persistence. By utilizing a tiered storage approach and a sophisticated relevance engine, it allows AI agents to "remember" architectural decisions, coding patterns, and project-specific requirements across disparate sessions and toolsets.