feat(memory): add lifecycle hooks, progressive disclosure, and auto-compress memory (#44)

* feat(memory): add lifecycle hooks, progressive disclosure, and auto-CLAUDE.md updates

- Add Claude Code lifecycle hooks (SessionStart, PostToolUse, SessionEnd)
  for automatic memory capture and injection
- Implement 3-layer progressive disclosure for token-optimized retrieval
  (Index ~50 tokens, Timeline ~200 tokens, Details ~600 tokens)
- Add CLAUDE.md auto-updater to populate LEARNED section with learnings
- Add auto-compression threshold trigger in observation store
- Add new CLI commands: `memory sync-claude` and `memory index`
- Update documentation with new memory features
- Remove 139 lines of unnecessary inline comments (code cleanup)

* fix(memory): address Devin review comments

- Fix double execution bug in MemoryHookManager by adding
  generateHookOutputFromResult methods to avoid calling execute() twice
- Add setConfig method to PostToolUseHook for runtime config updates
- Update manager.setConfig() to propagate config to all hooks

* fix(memory): address CodeRabbit review comments

- Fix cross-platform path handling using path.basename() instead of split('/')
  in claude-md-updater.ts, session-start.ts, and session-end.ts
- Fix onSessionEnd to call execute() before generateHookOutput to run
  compression/cleanup side effects
- Add generateHookOutputFromResult() to SessionEndHook to avoid double execution
- Call clearOldPendingErrors() in PostToolUseHook.execute() to prevent
  unbounded pendingErrors map growth
- Handle async checkAutoCompression() errors in observation-store.ts
- Add validation for compression threshold (must be positive integer)
- Fix docs/commands.mdx to use correct CLI flags (--limit, --tags)
- Clarify token accounting in progressive-disclosure smartRetrieve() JSDoc
- Use config.minRelevanceForCapture in session-start.ts instead of hardcoded value

* fix(memory): address additional CodeRabbit review comments

- Use nullish coalescing (??) for maxResults defaults in progressive-disclosure
- Guard against non-positive tokenBudget in smartRetrieve()
- Thread minRelevance option through to findRelevantIds()
- Fix memory index CLI to validate --limit and pass maxResults to getIndex()
This commit is contained in:
Rohit Ghumare
2026-02-05 11:26:31 +00:00
committed by GitHub
parent a994726952
commit 6d290171b7
19 changed files with 2638 additions and 163 deletions
+10 -2
View File
@@ -170,11 +170,19 @@ owner/repo@v1.2.3
```bash
skillkit memory status # View memory status
skillkit memory search <query> # Search learnings
skillkit memory compress # Compress observations
skillkit memory export <name> # Export as skill
skillkit memory compress # Compress observations to learnings
skillkit memory export <name> # Export learnings as skill
skillkit memory sync-claude # Update CLAUDE.md with learnings
skillkit memory index # View memory index (Layer 1)
skillkit memory --global # Use global memory
```
| Option | Purpose |
|--------|---------|
| `--global` | Use global memory instead of project |
| `--limit` | Limit number of results |
| `--tags` | Filter by tags |
## Translation Commands
```bash
+141 -9
View File
@@ -5,25 +5,51 @@ description: Persistent learning across AI agent sessions
# Memory System
Capture learnings from AI sessions and convert them into reusable skills.
Capture learnings from AI sessions and convert them into reusable skills. SkillKit's memory system provides automatic observation capture, intelligent compression, and token-optimized retrieval.
## Commands
```bash
skillkit memory status # View status
skillkit memory search <q> # Search learnings
skillkit memory compress # Compress observations
skillkit memory compress # Compress observations to learnings
skillkit memory export <name> # Export as skill
skillkit memory --global # Global memory
skillkit memory sync-claude # Update CLAUDE.md with learnings
skillkit memory index # View memory index (Layer 1)
skillkit memory --global # Global memory operations
```
## How It Works
1. **Observations** - Track patterns during sessions
2. **Compression** - Distill into reusable knowledge
3. **Injection** - Load into new sessions
### Observation → Learning Pipeline
1. **Observations** - Track patterns during sessions (tool use, errors, solutions)
2. **Compression** - Distill observations into reusable learnings
3. **Injection** - Load relevant learnings into new sessions
4. **Export** - Convert to shareable skills
### Lifecycle Hooks
SkillKit integrates with Claude Code's lifecycle hooks for automatic memory capture:
| Hook | Trigger | Action |
|------|---------|--------|
| **SessionStart** | Session begins | Inject relevant learnings |
| **PostToolUse** | Tool completes | Capture outcomes as observations |
| **SessionEnd** | Session closes | Compress observations to learnings |
### Progressive Disclosure (Token Optimization)
Memory retrieval uses a 3-layer system to minimize token usage:
| Layer | Content | ~Tokens |
|-------|---------|---------|
| **Index** | Titles, tags, timestamps | 50-100 |
| **Timeline** | Context, excerpts, activity | ~200 |
| **Details** | Full content, metadata | 500-1000 |
The system starts with Layer 1 and progressively fetches deeper layers based on relevance and token budget.
## Storage
```
@@ -31,17 +57,123 @@ skillkit memory --global # Global memory
├── observations/ # Raw session data
├── learnings/ # Compressed knowledge
└── index.json # Memory index
<project>/.skillkit/memory/
├── observations/ # Project-specific observations
├── learnings/ # Project learnings
└── index.json # Project memory index
```
## Auto-CLAUDE.md Updates
Sync your most effective learnings to CLAUDE.md:
```bash
skillkit memory sync-claude
```
This populates the `## LEARNED` section with high-effectiveness insights, giving your agent persistent context across sessions.
## Programmatic API
### Memory Compression
```typescript
import { MemoryCompressor, LearningStore } from '@skillkit/core'
const compressor = new MemoryCompressor()
const learning = await compressor.compress(observations)
const compressor = new MemoryCompressor(projectPath)
const { learnings } = await compressor.compress(observations)
const store = new LearningStore()
const store = new LearningStore('project', projectPath)
await store.add(learning)
const results = await store.search('authentication')
```
### Lifecycle Hooks
```typescript
import { MemoryHookManager } from '@skillkit/core'
const manager = new MemoryHookManager(projectPath)
// Session start - inject relevant learnings
const startResult = await manager.onSessionStart()
// After tool use - capture outcomes
await manager.onToolUse({
tool_name: 'Write',
tool_input: { file_path: '/src/auth.ts' },
tool_result: 'File written successfully',
duration_ms: 150
})
// Session end - compress to learnings
const endResult = await manager.onSessionEnd()
```
### Progressive Disclosure
```typescript
import { ProgressiveDisclosureManager } from '@skillkit/core'
const pdm = new ProgressiveDisclosureManager(projectPath)
// Layer 1: Index (~50 tokens each)
const index = pdm.getIndex({ includeGlobal: true })
// Layer 2: Timeline (~200 tokens each)
const timeline = pdm.getTimeline(['id1', 'id2'])
// Layer 3: Full details (~600 tokens each)
const details = pdm.getDetails(['id1'])
// Smart retrieval with token budget
const result = pdm.smartRetrieve('authentication patterns', 2000)
// Returns optimal layer based on budget
```
### CLAUDE.md Updater
```typescript
import { ClaudeMdUpdater } from '@skillkit/core'
const updater = new ClaudeMdUpdater(projectPath)
// Preview what would be updated
const preview = updater.preview({ minEffectiveness: 70 })
// Update CLAUDE.md
const result = updater.update({
minEffectiveness: 60,
maxLearnings: 20,
preserveManualEntries: true
})
```
## Configuration
Configure memory behavior in `.skillkit/config.json`:
```json
{
"memory": {
"enabled": true,
"autoInjectOnSessionStart": true,
"autoCaptureToolUse": true,
"autoCompressOnSessionEnd": true,
"minRelevanceForCapture": 30,
"maxTokensForInjection": 2000,
"compressionThreshold": 50
}
}
```
## Claude Code Integration
Generate hooks configuration for Claude Code:
```typescript
const manager = new MemoryHookManager(projectPath)
const config = manager.generateClaudeCodeHooksConfig()
// Outputs hooks.json format for Claude Code integration
```
+167 -12
View File
@@ -8,6 +8,9 @@ import {
getMemoryStatus,
createMemoryCompressor,
createMemoryInjector,
createClaudeMdUpdater,
syncGlobalClaudeMd,
createProgressiveDisclosureManager,
type Learning,
} from '@skillkit/core';
@@ -24,17 +27,19 @@ export class MemoryCommand extends Command {
captured from coding sessions across all AI agents.
Subcommands:
- status: Show current memory status
- search: Search memories by query
- list: List all learnings
- show: Show a specific learning
- compress: Compress observations into learnings
- export: Export a learning as a skill
- import: Import memories from another project
- clear: Clear session observations
- add: Manually add a learning
- rate: Rate a learning's effectiveness
- config: Configure memory settings
- status: Show current memory status
- search: Search memories by query
- list: List all learnings
- show: Show a specific learning
- compress: Compress observations into learnings
- export: Export a learning as a skill
- import: Import memories from another project
- clear: Clear session observations
- add: Manually add a learning
- rate: Rate a learning's effectiveness
- sync-claude: Sync learnings to CLAUDE.md
- index: Show memory index (progressive disclosure)
- config: Configure memory settings
`,
examples: [
['Show memory status', '$0 memory status'],
@@ -48,6 +53,8 @@ export class MemoryCommand extends Command {
['Clear session', '$0 memory clear'],
['Add manual learning', '$0 memory add --title "..." --content "..."'],
['Rate effectiveness', '$0 memory rate <id> 85'],
['Sync to CLAUDE.md', '$0 memory sync-claude'],
['Show memory index', '$0 memory index'],
],
});
@@ -146,9 +153,13 @@ export class MemoryCommand extends Command {
return this.rateLearning();
case 'config':
return this.showConfig();
case 'sync-claude':
return this.syncClaudeMd();
case 'index':
return this.showIndex();
default:
console.error(chalk.red(`Unknown action: ${action}`));
console.log(chalk.gray('Available actions: status, search, list, show, compress, export, import, clear, add, rate, config'));
console.log(chalk.gray('Available actions: status, search, list, show, compress, export, import, clear, add, rate, sync-claude, index, config'));
return 1;
}
}
@@ -761,6 +772,150 @@ export class MemoryCommand extends Command {
return 0;
}
/**
* Sync learnings to CLAUDE.md
*/
private async syncClaudeMd(): Promise<number> {
const projectPath = process.cwd();
if (this.global) {
if (this.dryRun) {
console.log(chalk.gray('(Dry run - previewing global CLAUDE.md sync)\n'));
}
const result = this.dryRun
? { updated: false, path: '~/.claude/CLAUDE.md', learningsAdded: 0, learningSummaries: [], previousLearnings: 0 }
: syncGlobalClaudeMd({ minEffectiveness: 60 });
if (this.dryRun) {
const globalStore = new LearningStore('global');
const learnings = globalStore.getAll()
.filter((l) => (l.effectiveness ?? 0) >= 60 || l.useCount >= 3)
.slice(0, 20);
console.log(chalk.cyan(`Would add ${learnings.length} learnings to global CLAUDE.md`));
for (const l of learnings.slice(0, 5)) {
console.log(` ${chalk.gray('●')} ${l.title}`);
}
if (learnings.length > 5) {
console.log(chalk.gray(` ... and ${learnings.length - 5} more`));
}
return 0;
}
if (result.updated) {
console.log(chalk.green(`✓ Updated global CLAUDE.md with ${result.learningsAdded} learnings`));
console.log(chalk.gray(` Path: ${result.path}`));
} else {
console.log(chalk.yellow('No learnings to sync to global CLAUDE.md'));
}
return 0;
}
const updater = createClaudeMdUpdater(projectPath);
if (this.dryRun) {
const preview = updater.preview({ minEffectiveness: 60 });
console.log(chalk.gray('(Dry run preview)\n'));
if (!preview.wouldUpdate) {
console.log(chalk.yellow('No learnings to sync to CLAUDE.md'));
return 0;
}
console.log(chalk.cyan(`Would add ${preview.learnings.length} learnings to CLAUDE.md\n`));
for (const learning of preview.learnings.slice(0, 5)) {
console.log(` ${chalk.gray('●')} ${learning.title}`);
}
if (preview.learnings.length > 5) {
console.log(chalk.gray(` ... and ${preview.learnings.length - 5} more`));
}
console.log(chalk.bold('\nFormatted section preview:'));
console.log(chalk.gray('─'.repeat(50)));
console.log(preview.formattedSection.slice(0, 500));
if (preview.formattedSection.length > 500) {
console.log(chalk.gray('...'));
}
return 0;
}
const result = updater.update({ minEffectiveness: 60 });
if (result.updated) {
console.log(chalk.green(`✓ Updated CLAUDE.md with ${result.learningsAdded} learnings`));
console.log(chalk.gray(` Path: ${result.path}`));
if (this.verbose && result.learningSummaries.length > 0) {
console.log(chalk.cyan('\nLearnings added:'));
for (const title of result.learningSummaries.slice(0, 10)) {
console.log(` ${chalk.gray('●')} ${title}`);
}
}
} else {
console.log(chalk.yellow('No learnings to sync to CLAUDE.md'));
}
return 0;
}
/**
* Show memory index (progressive disclosure Layer 1)
*/
private async showIndex(): Promise<number> {
const projectPath = process.cwd();
const manager = createProgressiveDisclosureManager(projectPath);
let maxResults = 50;
if (this.limit) {
const parsed = parseInt(this.limit, 10);
if (isNaN(parsed) || parsed <= 0) {
console.log(chalk.red('Invalid --limit value. Must be a positive number.'));
return 1;
}
maxResults = parsed;
}
const index = manager.getIndex({ includeGlobal: this.global, maxResults });
if (this.json) {
console.log(JSON.stringify(index, null, 2));
return 0;
}
console.log(chalk.bold(`\nMemory Index (${index.length} entries)\n`));
if (index.length === 0) {
console.log(chalk.gray('No learnings found.'));
return 0;
}
const displayLimit = this.limit ? parseInt(this.limit, 10) : 20;
const displayed = index.slice(0, displayLimit);
for (const entry of displayed) {
const effectiveness = entry.effectiveness !== undefined
? ` [${this.formatScore(entry.effectiveness)}%]`
: '';
const scope = entry.scope === 'global' ? chalk.magenta('[G]') : chalk.blue('[P]');
console.log(`${scope} ${chalk.gray(entry.id.slice(0, 8))} ${entry.title}${chalk.green(effectiveness)}`);
console.log(` Tags: ${entry.tags.join(', ')} | Uses: ${entry.useCount}`);
}
if (index.length > displayLimit) {
console.log(chalk.gray(`\n... and ${index.length - displayLimit} more (use --limit to show more)`));
}
console.log(chalk.gray('\nUse "skillkit memory show <id>" to view full details'));
return 0;
}
/**
* Format relevance/effectiveness score with color
*/
@@ -0,0 +1,444 @@
/**
* CLAUDE.md Auto-Updater
*
* Automatically updates CLAUDE.md with learnings from memory.
* Populates the LEARNED section with high-effectiveness insights.
*/
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { join, dirname, basename } from 'node:path';
import { homedir } from 'node:os';
import type { Learning } from './types.js';
import { LearningStore } from './learning-store.js';
/**
* CLAUDE.md section markers
*/
const SKILLKIT_MARKER = '<!-- Auto-populated by SkillKit -->';
/**
* Update options
*/
export interface ClaudeMdUpdateOptions {
minEffectiveness?: number;
maxLearnings?: number;
includeGlobal?: boolean;
preserveManualEntries?: boolean;
sectionTitle?: string;
addTimestamp?: boolean;
}
/**
* Default update options
*/
const DEFAULT_UPDATE_OPTIONS: Required<ClaudeMdUpdateOptions> = {
minEffectiveness: 60,
maxLearnings: 20,
includeGlobal: false,
preserveManualEntries: true,
sectionTitle: 'LEARNED',
addTimestamp: true,
};
/**
* Parsed CLAUDE.md structure
*/
export interface ParsedClaudeMd {
content: string;
sections: Map<string, { start: number; end: number; content: string }>;
hasLearnedSection: boolean;
learnedSectionContent?: string;
learnedSectionRange?: { start: number; end: number };
}
/**
* Update result
*/
export interface ClaudeMdUpdateResult {
updated: boolean;
path: string;
learningsAdded: number;
learningSummaries: string[];
previousLearnings: number;
}
/**
* CLAUDE.md Updater
*
* Manages automatic updates to CLAUDE.md with learnings from memory.
*/
export class ClaudeMdUpdater {
private projectPath: string;
private claudeMdPath: string;
constructor(projectPath: string, claudeMdPath?: string) {
this.projectPath = projectPath;
this.claudeMdPath = claudeMdPath || join(projectPath, 'CLAUDE.md');
}
/**
* Parse CLAUDE.md to extract structure
*/
parse(): ParsedClaudeMd {
if (!existsSync(this.claudeMdPath)) {
return {
content: '',
sections: new Map(),
hasLearnedSection: false,
};
}
const content = readFileSync(this.claudeMdPath, 'utf-8');
const sections = new Map<string, { start: number; end: number; content: string }>();
const lines = content.split('\n');
let currentSection: string | null = null;
let sectionStart = 0;
let sectionContent: string[] = [];
for (let i = 0; i < lines.length; i++) {
const line = lines[i];
const headerMatch = line.match(/^(#{1,3})\s+(.+)$/);
if (headerMatch) {
if (currentSection) {
sections.set(currentSection, {
start: sectionStart,
end: i - 1,
content: sectionContent.join('\n'),
});
}
currentSection = headerMatch[2].trim();
sectionStart = i;
sectionContent = [line];
} else if (currentSection) {
sectionContent.push(line);
}
}
if (currentSection) {
sections.set(currentSection, {
start: sectionStart,
end: lines.length - 1,
content: sectionContent.join('\n'),
});
}
const learnedSection = sections.get('LEARNED') || sections.get('Learned');
const hasLearnedSection = !!learnedSection;
return {
content,
sections,
hasLearnedSection,
learnedSectionContent: learnedSection?.content,
learnedSectionRange: learnedSection
? { start: learnedSection.start, end: learnedSection.end }
: undefined,
};
}
/**
* Get learnings to add to CLAUDE.md
*/
getLearningsForClaudeMd(options: ClaudeMdUpdateOptions = {}): Learning[] {
const opts = { ...DEFAULT_UPDATE_OPTIONS, ...options };
const projectStore = new LearningStore('project', this.projectPath);
let learnings = projectStore.getAll();
if (opts.includeGlobal) {
const globalStore = new LearningStore('global');
learnings = [...learnings, ...globalStore.getAll()];
}
return learnings
.filter((l) => (l.effectiveness ?? 0) >= opts.minEffectiveness || l.useCount >= 3)
.sort((a, b) => {
const scoreA = (a.effectiveness ?? 50) + a.useCount * 5;
const scoreB = (b.effectiveness ?? 50) + b.useCount * 5;
return scoreB - scoreA;
})
.slice(0, opts.maxLearnings);
}
/**
* Format learnings as CLAUDE.md LEARNED section
*/
formatLearnedSection(learnings: Learning[], options: ClaudeMdUpdateOptions = {}): string {
const opts = { ...DEFAULT_UPDATE_OPTIONS, ...options };
const lines: string[] = [];
lines.push(`## ${opts.sectionTitle}`);
lines.push('');
lines.push(SKILLKIT_MARKER);
if (opts.addTimestamp) {
lines.push(`<!-- Last updated: ${new Date().toISOString()} -->`);
}
lines.push('');
const byCategory = this.categorizeLearnings(learnings);
for (const [category, categoryLearnings] of byCategory) {
if (categoryLearnings.length > 0) {
lines.push(`### ${category}`);
for (const learning of categoryLearnings) {
const title = this.formatLearningTitle(learning);
const summary = this.extractSummary(learning.content);
lines.push(`${title}`);
lines.push(summary);
lines.push('');
}
}
}
return lines.join('\n');
}
/**
* Update CLAUDE.md with learnings
*/
update(options: ClaudeMdUpdateOptions = {}): ClaudeMdUpdateResult {
const opts = { ...DEFAULT_UPDATE_OPTIONS, ...options };
const learnings = this.getLearningsForClaudeMd(opts);
if (learnings.length === 0) {
return {
updated: false,
path: this.claudeMdPath,
learningsAdded: 0,
learningSummaries: [],
previousLearnings: 0,
};
}
const parsed = this.parse();
const newSection = this.formatLearnedSection(learnings, opts);
let newContent: string;
let previousLearnings = 0;
if (parsed.hasLearnedSection && parsed.learnedSectionRange) {
if (opts.preserveManualEntries) {
const existingContent = parsed.learnedSectionContent || '';
const manualEntries = this.extractManualEntries(existingContent);
previousLearnings = this.countLearnings(existingContent);
const combinedSection = this.combineWithManualEntries(newSection, manualEntries);
const lines = parsed.content.split('\n');
const before = lines.slice(0, parsed.learnedSectionRange.start).join('\n');
const after = lines.slice(parsed.learnedSectionRange.end + 1).join('\n');
newContent = before + (before ? '\n' : '') + combinedSection + (after ? '\n' + after : '');
} else {
const lines = parsed.content.split('\n');
const before = lines.slice(0, parsed.learnedSectionRange.start).join('\n');
const after = lines.slice(parsed.learnedSectionRange.end + 1).join('\n');
newContent = before + (before ? '\n' : '') + newSection + (after ? '\n' + after : '');
}
} else if (parsed.content) {
newContent = parsed.content + '\n\n' + newSection;
} else {
newContent = this.createNewClaudeMd(newSection);
}
const dir = dirname(this.claudeMdPath);
if (!existsSync(dir)) {
mkdirSync(dir, { recursive: true });
}
writeFileSync(this.claudeMdPath, newContent, 'utf-8');
return {
updated: true,
path: this.claudeMdPath,
learningsAdded: learnings.length,
learningSummaries: learnings.map((l) => l.title),
previousLearnings,
};
}
/**
* Preview update without writing
*/
preview(options: ClaudeMdUpdateOptions = {}): {
learnings: Learning[];
formattedSection: string;
wouldUpdate: boolean;
} {
const learnings = this.getLearningsForClaudeMd(options);
const formattedSection = this.formatLearnedSection(learnings, options);
return {
learnings,
formattedSection,
wouldUpdate: learnings.length > 0,
};
}
/**
* Check if CLAUDE.md exists
*/
exists(): boolean {
return existsSync(this.claudeMdPath);
}
/**
* Get CLAUDE.md path
*/
getPath(): string {
return this.claudeMdPath;
}
private categorizeLearnings(learnings: Learning[]): Map<string, Learning[]> {
const categories = new Map<string, Learning[]>();
for (const learning of learnings) {
let category = 'General';
if (learning.patterns?.includes('error-handling')) {
category = 'Error-Handling';
} else if (learning.patterns?.includes('debugging')) {
category = 'Debugging';
} else if (learning.patterns?.includes('architecture')) {
category = 'Architecture';
} else if (learning.patterns?.includes('workflow')) {
category = 'Workflow';
} else if (learning.tags.some((t) => t.includes('react') || t.includes('typescript'))) {
category = 'Code-Patterns';
}
const existing = categories.get(category) || [];
existing.push(learning);
categories.set(category, existing);
}
return categories;
}
private formatLearningTitle(learning: Learning): string {
const tags = learning.tags.slice(0, 3).join(', ');
return tags ? `**${tags}**: ${learning.title}` : `**${learning.title}**`;
}
private extractSummary(content: string): string {
const lines = content.split('\n').filter((l) => l.trim());
for (const line of lines) {
const cleaned = line.replace(/^#+\s*/, '').replace(/^\*\*.*?\*\*:?\s*/, '');
if (cleaned.length > 20 && !cleaned.startsWith('#')) {
return cleaned.slice(0, 200) + (cleaned.length > 200 ? '...' : '');
}
}
return content.slice(0, 200) + (content.length > 200 ? '...' : '');
}
private extractManualEntries(sectionContent: string): string[] {
const lines = sectionContent.split('\n');
const manualEntries: string[] = [];
let inManualEntry = false;
let currentEntry: string[] = [];
for (const line of lines) {
if (line.includes(SKILLKIT_MARKER)) {
inManualEntry = false;
continue;
}
if (line.startsWith('### ') && !line.includes('Auto-populated')) {
if (currentEntry.length > 0) {
manualEntries.push(currentEntry.join('\n'));
}
inManualEntry = true;
currentEntry = [line];
} else if (inManualEntry) {
currentEntry.push(line);
}
}
if (currentEntry.length > 0) {
manualEntries.push(currentEntry.join('\n'));
}
return manualEntries.filter((e) => e.trim().length > 0);
}
private combineWithManualEntries(autoSection: string, manualEntries: string[]): string {
if (manualEntries.length === 0) {
return autoSection;
}
const lines = autoSection.split('\n');
const combinedLines = [...lines];
combinedLines.push('');
combinedLines.push('### Manual Entries');
combinedLines.push('<!-- Preserved from previous edits -->');
combinedLines.push('');
for (const entry of manualEntries) {
combinedLines.push(entry);
combinedLines.push('');
}
return combinedLines.join('\n');
}
private countLearnings(content: string): number {
const matches = content.match(/^\*\*[^*]+\*\*/gm);
return matches ? matches.length : 0;
}
private createNewClaudeMd(learnedSection: string): string {
const projectName = basename(this.projectPath) || 'Project';
return `# ${projectName}
${learnedSection}
`;
}
}
/**
* Create a CLAUDE.md updater
*/
export function createClaudeMdUpdater(
projectPath: string,
claudeMdPath?: string
): ClaudeMdUpdater {
return new ClaudeMdUpdater(projectPath, claudeMdPath);
}
/**
* Update CLAUDE.md with learnings (standalone function)
*/
export function updateClaudeMd(
projectPath: string,
options: ClaudeMdUpdateOptions = {}
): ClaudeMdUpdateResult {
const updater = new ClaudeMdUpdater(projectPath);
return updater.update(options);
}
/**
* Sync global CLAUDE.md with global learnings
*/
export function syncGlobalClaudeMd(options: ClaudeMdUpdateOptions = {}): ClaudeMdUpdateResult {
const globalClaudeMdPath = join(homedir(), '.claude', 'CLAUDE.md');
const updater = new ClaudeMdUpdater(homedir(), globalClaudeMdPath);
const globalOpts: ClaudeMdUpdateOptions = {
...options,
includeGlobal: true,
sectionTitle: 'Global Learnings',
};
return updater.update(globalOpts);
}
-53
View File
@@ -95,7 +95,6 @@ export class RuleBasedCompressor implements CompressionEngine {
): Promise<CompressionResult> {
const opts = { ...DEFAULT_COMPRESSION_OPTIONS, ...options };
// Filter observations
const filtered = opts.includeLowRelevance
? observations
: observations.filter((o) => o.relevance >= 50);
@@ -116,36 +115,29 @@ export class RuleBasedCompressor implements CompressionEngine {
const learnings: CompressedLearning[] = [];
const processedIds: string[] = [];
// Group observations by type
const byType = this.groupByType(filtered);
// Extract error-solution pairs
const errorSolutionLearnings = this.extractErrorSolutionPairs(byType, opts);
learnings.push(...errorSolutionLearnings.learnings);
processedIds.push(...errorSolutionLearnings.processedIds);
// Extract decision patterns
const decisionLearnings = this.extractDecisionPatterns(byType, opts);
learnings.push(...decisionLearnings.learnings);
processedIds.push(...decisionLearnings.processedIds);
// Extract file change patterns
const fileChangeLearnings = this.extractFileChangePatterns(byType, opts);
learnings.push(...fileChangeLearnings.learnings);
processedIds.push(...fileChangeLearnings.processedIds);
// Extract tool usage patterns
const toolUsageLearnings = this.extractToolUsagePatterns(byType, opts);
learnings.push(...toolUsageLearnings.learnings);
processedIds.push(...toolUsageLearnings.processedIds);
// Filter by importance and limit
const finalLearnings = learnings
.filter((l) => l.importance >= opts.minImportance)
.sort((a, b) => b.importance - a.importance)
.slice(0, opts.maxLearnings);
// Add additional tags
if (opts.additionalTags.length > 0) {
for (const learning of finalLearnings) {
learning.tags = [...new Set([...learning.tags, ...opts.additionalTags])];
@@ -187,7 +179,6 @@ export class RuleBasedCompressor implements CompressionEngine {
const learnings: CompressedLearning[] = [];
const processedIds: string[] = [];
// Match errors with solutions
for (const error of errors) {
const errorText = error.content.error || error.content.action;
const matchingSolution = solutions.find((s) => {
@@ -195,21 +186,18 @@ export class RuleBasedCompressor implements CompressionEngine {
const solutionAction = s.content.action?.toLowerCase() || '';
const errorLower = errorText.toLowerCase();
// Require keyword similarity between error and solution
const hasKeywordMatch = this.hasSimilarKeywords(errorLower, solutionContext) ||
this.hasSimilarKeywords(errorLower, solutionAction);
if (!hasKeywordMatch) {
return false;
}
// Solution should indicate it's a fix/resolution, or have strong keyword overlap
const isSolutionIndicator = solutionContext.includes('fix') ||
solutionContext.includes('resolve') ||
solutionContext.includes('solution') ||
solutionAction.includes('fix') ||
solutionAction.includes('resolve');
// Require both keyword match AND solution indicator
return isSolutionIndicator || this.hasStrongKeywordOverlap(errorLower, solutionContext);
});
@@ -230,7 +218,6 @@ export class RuleBasedCompressor implements CompressionEngine {
processedIds.push(error.id, matchingSolution.id);
} else if (error.content.error) {
// Standalone error learning
const title = this.generateTitle('Error Pattern', errorText);
const content = this.formatStandaloneErrorContent(error);
const tags = this.extractTags([error]);
@@ -249,7 +236,6 @@ export class RuleBasedCompressor implements CompressionEngine {
}
}
// Process remaining solutions
for (const solution of solutions) {
if (!processedIds.includes(solution.id)) {
const title = this.generateTitle('Solution', solution.content.action);
@@ -310,7 +296,6 @@ export class RuleBasedCompressor implements CompressionEngine {
const learnings: CompressedLearning[] = [];
const processedIds: string[] = [];
// Group file changes by pattern (same files modified together)
const filePatterns = new Map<string, Observation[]>();
for (const change of fileChanges) {
const files = change.content.files || [];
@@ -320,7 +305,6 @@ export class RuleBasedCompressor implements CompressionEngine {
filePatterns.set(pattern, existing);
}
// Create learnings for significant patterns (2+ occurrences)
for (const [pattern, changes] of filePatterns) {
if (changes.length >= 2 || changes.some((c) => (c.content.files?.length || 0) > 3)) {
const title = `File Modification Pattern: ${pattern}`;
@@ -353,10 +337,8 @@ export class RuleBasedCompressor implements CompressionEngine {
const learnings: CompressedLearning[] = [];
const processedIds: string[] = [];
// Only extract if there are significant patterns
const allObs = [...toolUses, ...checkpoints];
if (allObs.length >= 5) {
// Group by common action patterns
const actionPatterns = new Map<string, Observation[]>();
for (const obs of allObs) {
const actionType = this.getActionType(obs.content.action);
@@ -390,7 +372,6 @@ export class RuleBasedCompressor implements CompressionEngine {
}
private generateTitle(prefix: string, text: string): string {
// Extract key words from text
const cleaned = text
.replace(/[^a-zA-Z0-9\s]/g, ' ')
.replace(/\s+/g, ' ')
@@ -534,7 +515,6 @@ Consider automating or documenting this workflow for future reference.
private getFilePattern(files: string[]): string {
if (files.length === 0) return 'unknown';
// Extract common directory
const dirs = files.map((f) => {
const parts = f.split('/');
return parts.slice(0, -1).join('/') || 'root';
@@ -545,7 +525,6 @@ Consider automating or documenting this workflow for future reference.
return uniqueDirs[0];
}
// Extract file types
const extensions = files.map((f) => {
const ext = f.split('.').pop() || 'unknown';
return ext;
@@ -568,7 +547,6 @@ Consider automating or documenting this workflow for future reference.
}
private hasSimilarKeywords(text1: string, text2: string): boolean {
// Normalize: lowercase and strip punctuation for better matching
const normalize = (word: string) => word.toLowerCase().replace(/[^a-z0-9]/g, '');
const words1 = text1.split(/\s+/).map(normalize).filter((w) => w.length > 3);
const words2 = new Set(text2.split(/\s+/).map(normalize).filter((w) => w.length > 3));
@@ -580,7 +558,6 @@ Consider automating or documenting this workflow for future reference.
* More strict than hasSimilarKeywords - requires at least 2 matching words
*/
private hasStrongKeywordOverlap(text1: string, text2: string): boolean {
// Normalize: lowercase and strip punctuation for better matching
const normalize = (word: string) => word.toLowerCase().replace(/[^a-z0-9]/g, '');
const words1 = text1.split(/\s+/).map(normalize).filter((w) => w.length > 3);
const words2 = new Set(text2.split(/\s+/).map(normalize).filter((w) => w.length > 3));
@@ -625,7 +602,6 @@ export class APIBasedCompressor implements CompressionEngine {
): Promise<CompressionResult> {
const opts = { ...DEFAULT_COMPRESSION_OPTIONS, ...options };
// Filter observations
const filtered = opts.includeLowRelevance
? observations
: observations.filter((o) => o.relevance >= 50);
@@ -643,26 +619,18 @@ export class APIBasedCompressor implements CompressionEngine {
};
}
// Format observations for the prompt
const observationsText = this.formatObservationsForPrompt(filtered);
// Build the prompt
const prompt = this.buildCompressionPrompt(observationsText, opts);
try {
// Call the API
const response = await this.callAPI(prompt);
// Parse the response
const learnings = this.parseAPIResponse(response, filtered);
// Filter and limit
const finalLearnings = learnings
.filter((l) => l.importance >= opts.minImportance)
.sort((a, b) => b.importance - a.importance)
.slice(0, opts.maxLearnings);
// Add additional tags
if (opts.additionalTags.length > 0) {
for (const learning of finalLearnings) {
learning.tags = [...new Set([...learning.tags, ...opts.additionalTags])];
@@ -686,7 +654,6 @@ export class APIBasedCompressor implements CompressionEngine {
},
};
} catch (error) {
// Fall back to rule-based compression on API failure
console.warn('API compression failed, falling back to rule-based:', error);
const fallback = new RuleBasedCompressor();
return fallback.compress(observations, options);
@@ -820,7 +787,6 @@ Generate up to ${opts.maxLearnings} learnings. Only include learnings with impor
private parseAPIResponse(response: string, observations: Observation[]): CompressedLearning[] {
try {
// Extract JSON from response (handle markdown code blocks)
let jsonStr = response;
const jsonMatch = response.match(/```(?:json)?\s*([\s\S]*?)```/);
if (jsonMatch) {
@@ -833,7 +799,6 @@ Generate up to ${opts.maxLearnings} learnings. Only include learnings with impor
throw new Error('Response is not an array');
}
// Validate and clean up each learning
const observationIds = new Set(observations.map((o) => o.id));
return parsed
.filter((item): item is CompressedLearning => {
@@ -847,7 +812,6 @@ Generate up to ${opts.maxLearnings} learnings. Only include learnings with impor
})
.map((item) => ({
...item,
// Validate source observation IDs
sourceObservationIds: (item.sourceObservationIds || []).filter((id: string) =>
observationIds.has(id)
),
@@ -884,7 +848,6 @@ export class MemoryCompressor {
projectPath,
options?.projectName
);
// For global scope, use home directory; for project scope, use project path
const indexBasePath = options?.scope === 'global' ? homedir() : projectPath;
this.indexStore = new MemoryIndexStore(indexBasePath, options?.scope === 'global');
this.projectName = options?.projectName;
@@ -926,10 +889,8 @@ export class MemoryCompressor {
projectName: this.projectName || options?.projectName,
};
// Compress observations
const result = await this.engine.compress(observations, compressionOptions);
// Store each learning
const storedLearnings: Learning[] = [];
for (const compressed of result.learnings) {
const learning = this.learningStore.add({
@@ -942,7 +903,6 @@ export class MemoryCompressor {
patterns: compressed.patterns,
});
// Index the learning
this.indexStore.indexLearning(learning);
storedLearnings.push(learning);
@@ -1004,12 +964,10 @@ export class LearningConsolidator {
* Merge two similar learnings
*/
merge(learning1: Learning, learning2: Learning): Omit<Learning, 'id' | 'createdAt' | 'updatedAt'> {
// Keep the more effective/used one as base
const base = this.getBetterLearning(learning1, learning2);
const other = base === learning1 ? learning2 : learning1;
return {
// Preserve the source from the base learning instead of hard-coding 'session'
source: base.source,
sourceObservations: [
...(base.sourceObservations || []),
@@ -1046,14 +1004,11 @@ export class LearningConsolidator {
continue;
}
// Merge the learnings
const merged = this.merge(l1, l2);
// Add the merged learning
const newLearning = store.add(merged);
index.indexLearning(newLearning);
// Remove the old learnings
store.delete(l1.id);
store.delete(l2.id);
index.removeLearning(l1.id);
@@ -1073,14 +1028,12 @@ export class LearningConsolidator {
private calculateSimilarity(l1: Learning, l2: Learning): number {
let score = 0;
// Title similarity (Jaccard)
const title1Words = new Set(l1.title.toLowerCase().split(/\s+/));
const title2Words = new Set(l2.title.toLowerCase().split(/\s+/));
const titleIntersection = [...title1Words].filter((w) => title2Words.has(w)).length;
const titleUnion = new Set([...title1Words, ...title2Words]).size;
score += (titleIntersection / titleUnion) * 0.3;
// Tag overlap
const tags1 = new Set(l1.tags);
const tags2 = new Set(l2.tags);
const tagIntersection = [...tags1].filter((t) => tags2.has(t)).length;
@@ -1089,7 +1042,6 @@ export class LearningConsolidator {
score += (tagIntersection / tagUnion) * 0.3;
}
// Pattern overlap
const patterns1 = new Set(l1.patterns || []);
const patterns2 = new Set(l2.patterns || []);
const patternIntersection = [...patterns1].filter((p) => patterns2.has(p)).length;
@@ -1098,7 +1050,6 @@ export class LearningConsolidator {
score += (patternIntersection / patternUnion) * 0.2;
}
// Content similarity (simple word overlap)
const content1Words = new Set(
l1.content
.toLowerCase()
@@ -1121,20 +1072,16 @@ export class LearningConsolidator {
}
private getBetterLearning(l1: Learning, l2: Learning): Learning {
// Prefer higher effectiveness
if (l1.effectiveness !== l2.effectiveness) {
return (l1.effectiveness || 0) > (l2.effectiveness || 0) ? l1 : l2;
}
// Prefer higher use count
if (l1.useCount !== l2.useCount) {
return l1.useCount > l2.useCount ? l1 : l2;
}
// Prefer more recent
return new Date(l1.updatedAt) > new Date(l2.updatedAt) ? l1 : l2;
}
private mergeContent(content1: string, content2: string): string {
// Simple merge: keep the longer one and add a note
if (content1.length >= content2.length) {
return content1;
}
@@ -39,30 +39,23 @@ export class MemoryEnabledEngine {
private userProgressCallback?: ExecutionProgressCallback;
constructor(projectPath: string, options: MemoryEnabledEngineOptions = {}) {
// Create memory observer
this.observer = new MemoryObserver(projectPath, options.sessionId, options.memoryConfig);
// Set default agent if provided
if (options.defaultAgent) {
this.observer.setAgent(options.defaultAgent);
}
// Store user's progress callback
this.userProgressCallback = options.onProgress;
// Create the combined progress callback
const combinedProgressCallback: ExecutionProgressCallback = (event: ExecutionProgressEvent) => {
// Forward to memory observer
const observerCallback = this.observer.createProgressCallback();
observerCallback(event);
// Forward to user's callback if provided
if (this.userProgressCallback) {
this.userProgressCallback(event);
}
};
// Create the underlying engine with the combined callback
this.engine = createExecutionEngine(projectPath, {
checkpointHandler: options.checkpointHandler,
onProgress: combinedProgressCallback,
@@ -76,22 +69,17 @@ export class MemoryEnabledEngine {
skill: ExecutableSkill,
options: ExecutionOptions = {}
): ReturnType<SkillExecutionEngine['execute']> {
// Set skill name in observer
this.observer.setSkillName(skill.name);
// Set agent if provided in options
if (options.agent) {
this.observer.setAgent(options.agent);
}
// Record execution start
this.observer.recordExecutionStart(skill.name, options.agent || 'claude-code');
try {
// Execute the skill
const result = await this.engine.execute(skill, options);
// Record file modifications from result
if (result.filesModified.length > 0) {
this.observer.recordFileModification(
result.filesModified,
@@ -99,14 +87,12 @@ export class MemoryEnabledEngine {
);
}
// Record any errors
if (result.error) {
this.observer.recordError(result.error, `Skill "${skill.name}" failed`);
}
return result;
} catch (error) {
// Record unexpected errors
const errorMessage = error instanceof Error ? error.message : String(error);
this.observer.recordError(errorMessage, `Unexpected error during skill "${skill.name}" execution`);
throw error;
+27
View File
@@ -0,0 +1,27 @@
/**
* Memory Hooks Module
*
* Provides Claude Code lifecycle hooks for automatic memory capture
* and injection at key session lifecycle events.
*/
export * from './types.js';
export {
SessionStartHook,
createSessionStartHook,
executeSessionStartHook,
} from './session-start.js';
export {
PostToolUseHook,
createPostToolUseHook,
executePostToolUseHook,
} from './post-tool-use.js';
export {
SessionEndHook,
createSessionEndHook,
executeSessionEndHook,
} from './session-end.js';
export {
MemoryHookManager,
createMemoryHookManager,
} from './manager.js';
+286
View File
@@ -0,0 +1,286 @@
/**
* Memory Hook Manager
*
* Unified manager for all memory lifecycle hooks.
* Provides a single interface for session memory management.
*/
import type { AgentType } from '../../types.js';
import type { Learning, Observation } from '../types.js';
import type {
MemoryHookConfig,
MemoryHookStats,
SessionStartContext,
SessionEndContext,
ToolUseEvent,
ClaudeCodeHookOutput,
} from './types.js';
import { DEFAULT_MEMORY_HOOK_CONFIG } from './types.js';
import { SessionStartHook } from './session-start.js';
import { PostToolUseHook } from './post-tool-use.js';
import { SessionEndHook } from './session-end.js';
import { randomUUID } from 'node:crypto';
/**
* Memory Hook Manager
*
* Coordinates all memory hooks for a session.
*/
export class MemoryHookManager {
private config: MemoryHookConfig;
private projectPath: string;
private agent: AgentType;
private sessionId: string;
private startedAt: string;
private sessionStartHook: SessionStartHook;
private postToolUseHook: PostToolUseHook;
private sessionEndHook: SessionEndHook;
private stats: MemoryHookStats;
constructor(
projectPath: string,
agent: AgentType = 'claude-code',
config: Partial<MemoryHookConfig> = {},
sessionId?: string
) {
this.projectPath = projectPath;
this.agent = agent;
this.config = { ...DEFAULT_MEMORY_HOOK_CONFIG, ...config };
this.sessionId = sessionId || randomUUID();
this.startedAt = new Date().toISOString();
this.sessionStartHook = new SessionStartHook(projectPath, agent, this.config);
this.postToolUseHook = new PostToolUseHook(projectPath, agent, this.config, this.sessionId);
this.sessionEndHook = new SessionEndHook(projectPath, agent, this.config);
this.stats = {
sessionId: this.sessionId,
startedAt: this.startedAt,
observationsCaptured: 0,
learningsInjected: 0,
tokensUsed: 0,
toolCallsCaptured: 0,
errorsRecorded: 0,
solutionsRecorded: 0,
};
}
/**
* Handle session start
*/
async onSessionStart(workingDirectory?: string): Promise<ClaudeCodeHookOutput> {
const context: SessionStartContext = {
session_id: this.sessionId,
project_path: this.projectPath,
agent: this.agent,
timestamp: new Date().toISOString(),
working_directory: workingDirectory,
};
const result = await this.sessionStartHook.execute(context);
this.stats.learningsInjected = result.learnings.length;
this.stats.tokensUsed = result.tokenCount;
return this.sessionStartHook.generateHookOutputFromResult(result);
}
/**
* Handle tool use
*/
async onToolUse(event: ToolUseEvent): Promise<ClaudeCodeHookOutput> {
const result = await this.postToolUseHook.execute(event);
if (result.captured) {
this.stats.observationsCaptured++;
this.stats.toolCallsCaptured++;
if (result.observation?.type === 'error') {
this.stats.errorsRecorded++;
} else if (result.observation?.type === 'solution') {
this.stats.solutionsRecorded++;
}
}
await this.checkAutoCompression();
return this.postToolUseHook.generateHookOutputFromResult(event, result);
}
/**
* Handle session end
*/
async onSessionEnd(toolCallsCount?: number): Promise<ClaudeCodeHookOutput> {
const context: SessionEndContext = {
session_id: this.sessionId,
project_path: this.projectPath,
agent: this.agent,
timestamp: new Date().toISOString(),
duration_ms: Date.now() - new Date(this.startedAt).getTime(),
tool_calls_count: toolCallsCount,
};
const result = await this.sessionEndHook.execute(context);
return this.sessionEndHook.generateHookOutputFromResult(result);
}
/**
* Record an error manually
*/
recordError(error: string, context: string): Observation {
const obs = this.postToolUseHook.recordError(error, context);
this.stats.observationsCaptured++;
this.stats.errorsRecorded++;
return obs;
}
/**
* Record a solution manually
*/
recordSolution(solution: string, context: string, relatedError?: string): Observation {
const obs = this.postToolUseHook.recordSolution(solution, context, relatedError);
this.stats.observationsCaptured++;
this.stats.solutionsRecorded++;
return obs;
}
/**
* Record a decision manually
*/
recordDecision(decision: string, options: string[], context: string): Observation {
const obs = this.postToolUseHook.recordDecision(decision, options, context);
this.stats.observationsCaptured++;
return obs;
}
/**
* Record file changes manually
*/
recordFileChange(files: string[], action: string, context: string): Observation {
const obs = this.postToolUseHook.recordFileChange(files, action, context);
this.stats.observationsCaptured++;
return obs;
}
/**
* Force compression (regardless of threshold)
*/
async forceCompress(): Promise<Learning[]> {
const result = await this.sessionEndHook.forceCompress(this.sessionId);
return result.learnings;
}
/**
* Preview compression without executing
*/
async previewCompression(): Promise<{
wouldCompress: boolean;
observationCount: number;
estimatedLearnings: number;
observationTypes: Record<string, number>;
}> {
return this.sessionEndHook.preview(this.sessionId);
}
/**
* Get current stats
*/
getStats(): MemoryHookStats {
return { ...this.stats };
}
/**
* Get session ID
*/
getSessionId(): string {
return this.sessionId;
}
/**
* Get observation count
*/
getObservationCount(): number {
return this.postToolUseHook.getObservationCount();
}
/**
* Get pending errors
*/
getPendingErrors(): Array<{ error: string; timestamp: string }> {
return this.postToolUseHook.getPendingErrors();
}
/**
* Get configuration
*/
getConfig(): MemoryHookConfig {
return { ...this.config };
}
/**
* Update configuration
*/
setConfig(config: Partial<MemoryHookConfig>): void {
this.config = { ...this.config, ...config };
this.sessionStartHook.setConfig(this.config);
this.postToolUseHook.setConfig(this.config);
this.sessionEndHook.setConfig(this.config);
}
/**
* Check if auto-compression should trigger
*/
private async checkAutoCompression(): Promise<void> {
if (!this.config.enabled) return;
const count = this.postToolUseHook.getObservationCount();
if (count >= this.config.compressionThreshold) {
await this.sessionEndHook.forceCompress(this.sessionId);
}
}
/**
* Generate Claude Code hooks.json configuration
*/
generateClaudeCodeHooksConfig(): Record<string, unknown> {
return {
hooks: [
{
matcher: '.*',
hooks: [
{
type: 'command',
command: `npx skillkit memory hook session-start --project "${this.projectPath}"`,
event: 'SessionStart',
},
{
type: 'command',
command: `npx skillkit memory hook post-tool-use --project "${this.projectPath}"`,
event: 'PostToolUse',
},
{
type: 'command',
command: `npx skillkit memory hook session-end --project "${this.projectPath}"`,
event: 'SessionEnd',
},
],
},
],
};
}
}
/**
* Create a memory hook manager
*/
export function createMemoryHookManager(
projectPath: string,
agent: AgentType = 'claude-code',
config: Partial<MemoryHookConfig> = {},
sessionId?: string
): MemoryHookManager {
return new MemoryHookManager(projectPath, agent, config, sessionId);
}
@@ -0,0 +1,442 @@
/**
* Post Tool Use Hook
*
* Captures tool outcomes as observations after each tool use in Claude Code.
* This enables automatic memory capture without manual intervention.
*/
import type { AgentType } from '../../types.js';
import type { Observation, ObservationType, ObservationContent } from '../types.js';
import type {
ToolUseEvent,
ToolUseCaptureResult,
MemoryHookConfig,
ClaudeCodeHookOutput,
} from './types.js';
import { DEFAULT_MEMORY_HOOK_CONFIG } from './types.js';
import { ObservationStore } from '../observation-store.js';
/**
* Tool categories for classification
*/
const TOOL_CATEGORIES: Record<string, ObservationType> = {
Read: 'tool_use',
Write: 'file_change',
Edit: 'file_change',
Bash: 'tool_use',
Glob: 'tool_use',
Grep: 'tool_use',
WebFetch: 'tool_use',
WebSearch: 'tool_use',
Task: 'checkpoint',
AskUserQuestion: 'decision',
};
/**
* Relevance scores by tool type
*/
const TOOL_RELEVANCE: Record<string, number> = {
Write: 70,
Edit: 70,
Bash: 60,
Task: 65,
AskUserQuestion: 75,
WebFetch: 50,
WebSearch: 50,
Read: 30,
Glob: 25,
Grep: 30,
};
/**
* Post Tool Use Hook Handler
*
* Captures tool outcomes and stores them as observations.
*/
export class PostToolUseHook {
private config: MemoryHookConfig;
private agent: AgentType;
private store: ObservationStore;
private pendingErrors: Map<string, { error: string; timestamp: string }> = new Map();
constructor(
projectPath: string,
agent: AgentType = 'claude-code',
config: Partial<MemoryHookConfig> = {},
sessionId?: string
) {
this.agent = agent;
this.config = { ...DEFAULT_MEMORY_HOOK_CONFIG, ...config };
this.store = new ObservationStore(projectPath, sessionId);
}
/**
* Execute the post tool use hook
*/
async execute(event: ToolUseEvent): Promise<ToolUseCaptureResult> {
this.clearOldPendingErrors();
if (!this.config.enabled || !this.config.autoCaptureToolUse) {
return { captured: false, reason: 'Hook disabled' };
}
if (this.shouldExcludeTool(event.tool_name)) {
return { captured: false, reason: `Tool ${event.tool_name} is excluded` };
}
const relevance = this.calculateRelevance(event);
if (relevance < this.config.minRelevanceForCapture) {
return { captured: false, reason: `Relevance ${relevance} below threshold` };
}
const observationType = this.getObservationType(event);
const content = this.extractContent(event);
if (event.is_error) {
const errorId = this.generateErrorId(content.error || content.action);
this.pendingErrors.set(errorId, {
error: content.error || content.action,
timestamp: new Date().toISOString(),
});
}
const matchingSolution = event.is_error ? undefined : this.findMatchingSolution(content);
if (matchingSolution) {
content.solution = content.action;
content.context = `Solution for: ${matchingSolution.error}`;
}
const observation = this.store.add(
observationType,
content,
this.agent,
matchingSolution ? 95 : relevance
);
return { captured: true, observation };
}
/**
* Generate Claude Code hook output format
*/
async generateHookOutput(event: ToolUseEvent): Promise<ClaudeCodeHookOutput> {
const result = await this.execute(event);
return this.generateHookOutputFromResult(event, result);
}
/**
* Generate hook output from pre-computed result (avoids double execution)
*/
generateHookOutputFromResult(event: ToolUseEvent, result: ToolUseCaptureResult): ClaudeCodeHookOutput {
return {
continue: true,
message: result.captured
? `Observation captured: ${event.tool_name}`
: undefined,
};
}
/**
* Get configuration
*/
getConfig(): MemoryHookConfig {
return { ...this.config };
}
/**
* Update configuration
*/
setConfig(config: Partial<MemoryHookConfig>): void {
this.config = { ...this.config, ...config };
}
/**
* Record an error explicitly
*/
recordError(error: string, context: string): Observation {
const errorId = this.generateErrorId(error);
this.pendingErrors.set(errorId, {
error,
timestamp: new Date().toISOString(),
});
return this.store.add(
'error',
{
action: 'Error encountered',
context,
error,
tags: ['error'],
},
this.agent,
80
);
}
/**
* Record a solution explicitly
*/
recordSolution(solution: string, context: string, relatedError?: string): Observation {
let relevance = 70;
let solutionContext = context;
if (relatedError) {
const errorId = this.generateErrorId(relatedError);
if (this.pendingErrors.has(errorId)) {
this.pendingErrors.delete(errorId);
relevance = 95;
solutionContext = `Solution for: ${relatedError}`;
}
}
return this.store.add(
'solution',
{
action: solution,
context: solutionContext,
solution,
tags: ['solution'],
},
this.agent,
relevance
);
}
/**
* Record a decision explicitly
*/
recordDecision(decision: string, options: string[], context: string): Observation {
return this.store.add(
'decision',
{
action: decision,
context: `Options: ${options.join(', ')}. Context: ${context}`,
tags: ['decision', 'architecture'],
},
this.agent,
75
);
}
/**
* Record file modifications
*/
recordFileChange(files: string[], action: string, context: string): Observation {
return this.store.add(
'file_change',
{
action,
context,
files,
tags: ['file-change'],
},
this.agent,
files.length > 3 ? 75 : 60
);
}
/**
* Get pending errors that haven't been resolved
*/
getPendingErrors(): Array<{ error: string; timestamp: string }> {
return Array.from(this.pendingErrors.values());
}
/**
* Clear old pending errors (older than 30 minutes)
*/
clearOldPendingErrors(): number {
const thirtyMinutesAgo = Date.now() - 30 * 60 * 1000;
let cleared = 0;
for (const [id, { timestamp }] of this.pendingErrors) {
if (new Date(timestamp).getTime() < thirtyMinutesAgo) {
this.pendingErrors.delete(id);
cleared++;
}
}
return cleared;
}
/**
* Get observation store
*/
getStore(): ObservationStore {
return this.store;
}
/**
* Get observation count
*/
getObservationCount(): number {
return this.store.count();
}
private shouldExcludeTool(toolName: string): boolean {
return this.config.excludeTools?.includes(toolName) ?? false;
}
private calculateRelevance(event: ToolUseEvent): number {
let relevance = TOOL_RELEVANCE[event.tool_name] || 50;
if (event.is_error) {
relevance = Math.max(relevance, 80);
}
if (event.duration_ms && event.duration_ms > 10000) {
relevance = Math.min(relevance + 10, 100);
}
const result = event.tool_result || '';
if (result.includes('error') || result.includes('Error') || result.includes('failed')) {
relevance = Math.max(relevance, 75);
}
if (result.includes('success') || result.includes('created') || result.includes('updated')) {
relevance = Math.min(relevance + 5, 100);
}
return relevance;
}
private getObservationType(event: ToolUseEvent): ObservationType {
if (event.is_error) {
return 'error';
}
return TOOL_CATEGORIES[event.tool_name] || 'tool_use';
}
private extractContent(event: ToolUseEvent): ObservationContent {
const content: ObservationContent = {
action: `${event.tool_name}: ${this.summarizeInput(event.tool_input)}`,
context: this.extractContext(event),
tags: [event.tool_name.toLowerCase()],
};
if (event.is_error && event.tool_result) {
content.error = event.tool_result.slice(0, 500);
}
if (event.tool_result && !event.is_error) {
content.result = event.tool_result.slice(0, 200);
}
const files = this.extractFiles(event);
if (files.length > 0) {
content.files = files;
}
return content;
}
private summarizeInput(input: Record<string, unknown>): string {
if (input.file_path) return String(input.file_path);
if (input.pattern) return String(input.pattern);
if (input.command) {
const cmd = String(input.command);
return cmd.length > 100 ? cmd.slice(0, 100) + '...' : cmd;
}
if (input.query) return String(input.query).slice(0, 100);
const keys = Object.keys(input);
if (keys.length === 0) return '(no input)';
return keys.slice(0, 3).join(', ');
}
private extractContext(event: ToolUseEvent): string {
const parts: string[] = [];
if (event.duration_ms) {
parts.push(`Duration: ${event.duration_ms}ms`);
}
if (event.is_error) {
parts.push('Result: Error');
} else if (event.tool_result) {
const resultPreview = event.tool_result.slice(0, 100);
parts.push(`Result: ${resultPreview}${event.tool_result.length > 100 ? '...' : ''}`);
}
return parts.join('. ') || 'No additional context';
}
private extractFiles(event: ToolUseEvent): string[] {
const files: string[] = [];
if (event.tool_input.file_path) {
files.push(String(event.tool_input.file_path));
}
if (event.tool_input.path) {
files.push(String(event.tool_input.path));
}
return files;
}
private generateErrorId(error: string): string {
const normalized = error
.toLowerCase()
.replace(/[0-9]+/g, 'N')
.replace(/['"`]/g, '')
.replace(/\s+/g, ' ')
.trim()
.slice(0, 100);
return normalized;
}
private findMatchingSolution(content: ObservationContent): { error: string } | undefined {
const actionLower = content.action.toLowerCase();
const contextLower = content.context.toLowerCase();
for (const [errorId, errorData] of this.pendingErrors) {
const hasKeywordMatch =
actionLower.includes('fix') ||
actionLower.includes('resolve') ||
actionLower.includes('solution') ||
contextLower.includes('fix') ||
contextLower.includes('resolve');
if (hasKeywordMatch) {
const errorWords = errorId.split(' ').filter((w) => w.length > 3);
const textWords = new Set((actionLower + ' ' + contextLower).split(/\s+/));
const matchCount = errorWords.filter((w) => textWords.has(w)).length;
if (matchCount >= 2 || (matchCount >= 1 && hasKeywordMatch)) {
this.pendingErrors.delete(errorId);
return errorData;
}
}
}
return undefined;
}
}
/**
* Create a post tool use hook handler
*/
export function createPostToolUseHook(
projectPath: string,
agent: AgentType = 'claude-code',
config: Partial<MemoryHookConfig> = {},
sessionId?: string
): PostToolUseHook {
return new PostToolUseHook(projectPath, agent, config, sessionId);
}
/**
* Execute post tool use hook (standalone function for scripts)
*/
export async function executePostToolUseHook(
projectPath: string,
event: ToolUseEvent,
config: Partial<MemoryHookConfig> = {},
sessionId?: string
): Promise<ToolUseCaptureResult> {
const hook = new PostToolUseHook(projectPath, 'claude-code', config, sessionId);
return hook.execute(event);
}
@@ -0,0 +1,227 @@
/**
* Session End Hook
*
* Compresses observations to learnings when a Claude Code session ends.
* This enables automatic memory consolidation without manual intervention.
*/
import { basename } from 'node:path';
import type { AgentType } from '../../types.js';
import type {
SessionEndContext,
SessionEndResult,
MemoryHookConfig,
ClaudeCodeHookOutput,
} from './types.js';
import { DEFAULT_MEMORY_HOOK_CONFIG } from './types.js';
import { ObservationStore } from '../observation-store.js';
import { MemoryCompressor } from '../compressor.js';
/**
* Session End Hook Handler
*
* Compresses observations collected during the session into learnings.
*/
export class SessionEndHook {
private config: MemoryHookConfig;
private projectPath: string;
private agent: AgentType;
constructor(
projectPath: string,
agent: AgentType = 'claude-code',
config: Partial<MemoryHookConfig> = {}
) {
this.projectPath = projectPath;
this.agent = agent;
this.config = { ...DEFAULT_MEMORY_HOOK_CONFIG, ...config };
}
/**
* Execute the session end hook
*/
async execute(context: SessionEndContext): Promise<SessionEndResult> {
if (!this.config.enabled || !this.config.autoCompressOnSessionEnd) {
return {
compressed: false,
observationCount: 0,
learningCount: 0,
learnings: [],
};
}
const store = new ObservationStore(this.projectPath, context.session_id);
const observations = store.getAll();
if (observations.length < 3) {
return {
compressed: false,
observationCount: observations.length,
learningCount: 0,
learnings: [],
};
}
const projectName = context.project_path
? basename(context.project_path.replace(/\/+$/, '')) || undefined
: undefined;
const compressor = new MemoryCompressor(this.projectPath, {
scope: 'project',
projectName,
});
const { learnings, result } = await compressor.compressAndStore(observations, {
minObservations: 3,
maxLearnings: 10,
minImportance: 4,
includeLowRelevance: false,
additionalTags: ['session-end', this.agent],
});
if (result.processedObservationIds.length > 0) {
store.deleteMany(result.processedObservationIds);
}
return {
compressed: learnings.length > 0,
observationCount: observations.length,
learningCount: learnings.length,
learnings,
};
}
/**
* Generate Claude Code hook output format
*/
async generateHookOutput(context: SessionEndContext): Promise<ClaudeCodeHookOutput> {
const result = await this.execute(context);
return this.generateHookOutputFromResult(result);
}
/**
* Generate hook output from pre-computed result (avoids double execution)
*/
generateHookOutputFromResult(result: SessionEndResult): ClaudeCodeHookOutput {
let message: string | undefined;
if (result.compressed) {
message = `Session memory: ${result.observationCount} observations → ${result.learningCount} learnings`;
}
return {
continue: true,
message,
};
}
/**
* Force compression regardless of settings
*/
async forceCompress(sessionId?: string): Promise<SessionEndResult> {
const store = new ObservationStore(this.projectPath, sessionId);
const observations = store.getAll();
if (observations.length === 0) {
return {
compressed: false,
observationCount: 0,
learningCount: 0,
learnings: [],
};
}
const compressor = new MemoryCompressor(this.projectPath, {
scope: 'project',
});
const { learnings, result } = await compressor.compressAndStore(observations, {
minObservations: 1,
maxLearnings: 20,
minImportance: 3,
includeLowRelevance: true,
});
if (result.processedObservationIds.length > 0) {
store.deleteMany(result.processedObservationIds);
}
return {
compressed: learnings.length > 0,
observationCount: observations.length,
learningCount: learnings.length,
learnings,
};
}
/**
* Preview what would be compressed (dry-run)
*/
async preview(sessionId?: string): Promise<{
wouldCompress: boolean;
observationCount: number;
estimatedLearnings: number;
observationTypes: Record<string, number>;
}> {
const store = new ObservationStore(this.projectPath, sessionId);
const observations = store.getAll();
const types: Record<string, number> = {};
for (const obs of observations) {
types[obs.type] = (types[obs.type] || 0) + 1;
}
const compressor = new MemoryCompressor(this.projectPath, {
scope: 'project',
});
const result = await compressor.compress(observations, {
minObservations: 3,
maxLearnings: 10,
minImportance: 4,
});
return {
wouldCompress: result.learnings.length > 0,
observationCount: observations.length,
estimatedLearnings: result.learnings.length,
observationTypes: types,
};
}
/**
* Get configuration
*/
getConfig(): MemoryHookConfig {
return { ...this.config };
}
/**
* Update configuration
*/
setConfig(config: Partial<MemoryHookConfig>): void {
this.config = { ...this.config, ...config };
}
}
/**
* Create a session end hook handler
*/
export function createSessionEndHook(
projectPath: string,
agent: AgentType = 'claude-code',
config: Partial<MemoryHookConfig> = {}
): SessionEndHook {
return new SessionEndHook(projectPath, agent, config);
}
/**
* Execute session end hook (standalone function for scripts)
*/
export async function executeSessionEndHook(
projectPath: string,
context: SessionEndContext,
config: Partial<MemoryHookConfig> = {}
): Promise<SessionEndResult> {
const hook = new SessionEndHook(projectPath, context.agent || 'claude-code', config);
return hook.execute(context);
}
@@ -0,0 +1,177 @@
/**
* Session Start Hook
*
* Injects relevant memories when a Claude Code session starts.
* This hook runs at the beginning of each session to provide context
* from previous sessions.
*/
import { basename } from 'node:path';
import type { AgentType } from '../../types.js';
import type {
SessionStartContext,
SessionStartResult,
MemoryHookConfig,
ClaudeCodeHookOutput,
} from './types.js';
import { DEFAULT_MEMORY_HOOK_CONFIG } from './types.js';
import { MemoryInjector } from '../injector.js';
import { getMemoryStatus } from '../initializer.js';
/**
* Session Start Hook Handler
*
* Retrieves and formats relevant memories for injection at session start.
*/
export class SessionStartHook {
private config: MemoryHookConfig;
private projectPath: string;
private agent: AgentType;
constructor(
projectPath: string,
agent: AgentType = 'claude-code',
config: Partial<MemoryHookConfig> = {}
) {
this.projectPath = projectPath;
this.agent = agent;
this.config = { ...DEFAULT_MEMORY_HOOK_CONFIG, ...config };
}
/**
* Execute the session start hook
*/
async execute(context: SessionStartContext): Promise<SessionStartResult> {
if (!this.config.enabled || !this.config.autoInjectOnSessionStart) {
return {
injected: false,
learnings: [],
tokenCount: 0,
formattedContent: '',
};
}
const status = getMemoryStatus(this.projectPath);
if (!status.projectMemoryExists && !status.globalMemoryExists) {
return {
injected: false,
learnings: [],
tokenCount: 0,
formattedContent: '',
};
}
const projectName = context.project_path
? basename(context.project_path.replace(/\/+$/, '')) || undefined
: undefined;
const injector = new MemoryInjector(this.projectPath, projectName);
const result = await injector.injectForAgent(this.agent, {
maxTokens: this.config.maxTokensForInjection,
minRelevance: this.config.minRelevanceForCapture,
maxLearnings: 10,
includeGlobal: true,
disclosureLevel: 'preview',
});
const learnings = result.memories.map((m) => m.learning);
return {
injected: result.memories.length > 0,
learnings,
tokenCount: result.totalTokens,
formattedContent: result.formattedContent,
};
}
/**
* Generate Claude Code hook output format
*/
async generateHookOutput(context: SessionStartContext): Promise<ClaudeCodeHookOutput> {
const result = await this.execute(context);
return this.generateHookOutputFromResult(result);
}
/**
* Generate hook output from pre-computed result (avoids double execution)
*/
generateHookOutputFromResult(result: SessionStartResult): ClaudeCodeHookOutput {
if (!result.injected || result.learnings.length === 0) {
return { continue: true };
}
return {
continue: true,
inject: this.formatInjection(result),
};
}
/**
* Format learnings for injection into Claude Code context
*/
private formatInjection(result: SessionStartResult): string {
if (result.learnings.length === 0) {
return '';
}
const lines: string[] = [
'<skillkit-memories>',
`<!-- ${result.learnings.length} relevant learnings from previous sessions (${result.tokenCount} tokens) -->`,
'',
];
for (const learning of result.learnings) {
lines.push(`## ${learning.title}`);
lines.push(`Tags: ${learning.tags.join(', ')}`);
if (learning.frameworks && learning.frameworks.length > 0) {
lines.push(`Frameworks: ${learning.frameworks.join(', ')}`);
}
lines.push('');
const preview = learning.content.slice(0, 200);
lines.push(preview + (learning.content.length > 200 ? '...' : ''));
lines.push('');
}
lines.push('</skillkit-memories>');
return lines.join('\n');
}
/**
* Get configuration
*/
getConfig(): MemoryHookConfig {
return { ...this.config };
}
/**
* Update configuration
*/
setConfig(config: Partial<MemoryHookConfig>): void {
this.config = { ...this.config, ...config };
}
}
/**
* Create a session start hook handler
*/
export function createSessionStartHook(
projectPath: string,
agent: AgentType = 'claude-code',
config: Partial<MemoryHookConfig> = {}
): SessionStartHook {
return new SessionStartHook(projectPath, agent, config);
}
/**
* Execute session start hook (standalone function for scripts)
*/
export async function executeSessionStartHook(
projectPath: string,
context: SessionStartContext,
config: Partial<MemoryHookConfig> = {}
): Promise<SessionStartResult> {
const hook = new SessionStartHook(projectPath, context.agent || 'claude-code', config);
return hook.execute(context);
}
+139
View File
@@ -0,0 +1,139 @@
/**
* Memory Hooks Types
*
* Types for Claude Code lifecycle hooks that integrate with SkillKit memory.
*/
import type { AgentType } from '../../types.js';
import type { Learning, Observation } from '../types.js';
/**
* Claude Code hook event types
*/
export type ClaudeCodeHookEvent =
| 'SessionStart'
| 'SessionResume'
| 'SessionEnd'
| 'PreToolUse'
| 'PostToolUse'
| 'UserPromptSubmit'
| 'PreCompact'
| 'Notification'
| 'Stop';
/**
* Tool use event for PostToolUse hook
*/
export interface ToolUseEvent {
tool_name: string;
tool_input: Record<string, unknown>;
tool_result?: string;
is_error?: boolean;
duration_ms?: number;
}
/**
* Session start event context
*/
export interface SessionStartContext {
session_id: string;
project_path: string;
agent: AgentType;
timestamp: string;
working_directory?: string;
}
/**
* Session end event context
*/
export interface SessionEndContext {
session_id: string;
project_path: string;
agent: AgentType;
timestamp: string;
duration_ms?: number;
tool_calls_count?: number;
}
/**
* Memory hook configuration
*/
export interface MemoryHookConfig {
enabled: boolean;
autoInjectOnSessionStart: boolean;
autoCaptureToolUse: boolean;
autoCompressOnSessionEnd: boolean;
minRelevanceForCapture: number;
maxTokensForInjection: number;
compressionThreshold: number;
capturePatterns?: string[];
excludeTools?: string[];
}
/**
* Default memory hook configuration
*/
export const DEFAULT_MEMORY_HOOK_CONFIG: MemoryHookConfig = {
enabled: true,
autoInjectOnSessionStart: true,
autoCaptureToolUse: true,
autoCompressOnSessionEnd: true,
minRelevanceForCapture: 30,
maxTokensForInjection: 2000,
compressionThreshold: 50,
capturePatterns: ['*'],
excludeTools: ['Read', 'Glob', 'Grep'],
};
/**
* Session start hook result
*/
export interface SessionStartResult {
injected: boolean;
learnings: Learning[];
tokenCount: number;
formattedContent: string;
}
/**
* Tool use capture result
*/
export interface ToolUseCaptureResult {
captured: boolean;
observation?: Observation;
reason?: string;
}
/**
* Session end hook result
*/
export interface SessionEndResult {
compressed: boolean;
observationCount: number;
learningCount: number;
learnings: Learning[];
}
/**
* Hook script output format for Claude Code
*/
export interface ClaudeCodeHookOutput {
continue: boolean;
message?: string;
inject?: string;
suppress?: boolean;
}
/**
* Memory hook statistics
*/
export interface MemoryHookStats {
sessionId: string;
startedAt: string;
observationsCaptured: number;
learningsInjected: number;
tokensUsed: number;
toolCallsCaptured: number;
errorsRecorded: number;
solutionsRecorded: number;
}
+27 -4
View File
@@ -1,8 +1,9 @@
// Memory Module - Cross-Agent Session Memory System
// Provides persistent memory across all AI coding agents
export * from './types.js';
export { ObservationStore } from './observation-store.js';
export {
ObservationStore,
type AutoCompressCallback,
type ObservationStoreOptions,
} from './observation-store.js';
export { LearningStore } from './learning-store.js';
export { MemoryIndexStore } from './memory-index.js';
export {
@@ -48,3 +49,25 @@ export {
type InjectedMemory,
type InjectionResult,
} from './injector.js';
export * from './hooks/index.js';
export {
ClaudeMdUpdater,
createClaudeMdUpdater,
updateClaudeMd,
syncGlobalClaudeMd,
type ClaudeMdUpdateOptions,
type ClaudeMdUpdateResult,
type ParsedClaudeMd,
} from './claude-md-updater.js';
export {
ProgressiveDisclosureManager,
createProgressiveDisclosureManager,
type IndexEntry,
type TimelineEntry,
type DetailsEntry,
type ActivityPoint,
type ProgressiveDisclosureOptions,
} from './progressive-disclosure.js';
-2
View File
@@ -30,12 +30,10 @@ export function getMemoryPaths(projectPath: string): MemoryPaths {
export function initializeMemoryDirectory(projectPath: string): MemoryPaths {
const paths = getMemoryPaths(projectPath);
// Create project memory directory
if (!existsSync(paths.projectMemoryDir)) {
mkdirSync(paths.projectMemoryDir, { recursive: true });
}
// Create global memory directory
if (!existsSync(paths.globalMemoryDir)) {
mkdirSync(paths.globalMemoryDir, { recursive: true });
}
-20
View File
@@ -109,24 +109,19 @@ export class MemoryInjector {
async getRelevantMemories(options: InjectionOptions = {}): Promise<InjectedMemory[]> {
const opts = { ...DEFAULT_OPTIONS, ...options };
// Collect all learnings
const projectLearnings = this.projectStore.getAll();
const globalLearnings = opts.includeGlobal ? this.globalStore.getAll() : [];
const allLearnings = [...projectLearnings, ...globalLearnings];
// Score each learning for relevance
const scored = allLearnings.map((learning) => ({
learning,
...this.scoreLearning(learning, opts),
}));
// Filter by minimum relevance
const filtered = scored.filter((s) => s.relevanceScore >= opts.minRelevance);
// Sort by relevance (descending)
filtered.sort((a, b) => b.relevanceScore - a.relevanceScore);
// Limit to max learnings
return filtered.slice(0, opts.maxLearnings);
}
@@ -145,7 +140,6 @@ export class MemoryInjector {
patterns: [] as string[],
};
// Match by frameworks from project context
if (this.projectContext?.stack) {
const projectFrameworks = this.extractFrameworkNames();
const learningFrameworks = learning.frameworks || [];
@@ -158,7 +152,6 @@ export class MemoryInjector {
}
}
// Match by explicitly requested tags
if (options.tags && options.tags.length > 0) {
const requestedTags = new Set(options.tags.map((t) => t.toLowerCase()));
for (const tag of learning.tags) {
@@ -169,7 +162,6 @@ export class MemoryInjector {
}
}
// Match by current task keywords
if (options.currentTask) {
const taskKeywords = this.extractKeywords(options.currentTask);
const learningKeywords = [
@@ -189,22 +181,17 @@ export class MemoryInjector {
}
}
// Match by patterns
if (learning.patterns && learning.patterns.length > 0) {
// Patterns are valuable - boost score
score += learning.patterns.length * 5;
matchedBy.patterns.push(...learning.patterns);
}
// Boost by effectiveness if known
if (learning.effectiveness !== undefined) {
score += (learning.effectiveness / 100) * 20;
}
// Boost by use count (popular learnings are likely valuable)
score += Math.min(learning.useCount * 2, 15);
// Boost recent learnings
const daysSinceUpdate = this.daysSince(learning.updatedAt);
if (daysSinceUpdate < 7) {
score += 10;
@@ -212,10 +199,8 @@ export class MemoryInjector {
score += 5;
}
// Cap score at 100
score = Math.min(score, 100);
// Estimate token count
const tokenEstimate = this.estimateTokens(learning, options.disclosureLevel || 'preview');
return {
@@ -304,7 +289,6 @@ export class MemoryInjector {
const opts = { ...DEFAULT_OPTIONS, ...options };
const allMemories = await this.getRelevantMemories(opts);
// Select memories within token budget
const selected: InjectedMemory[] = [];
let totalTokens = 0;
let truncated = 0;
@@ -314,7 +298,6 @@ export class MemoryInjector {
selected.push(memory);
totalTokens += memory.tokenEstimate;
// Increment use count
if (memory.learning.scope === 'project') {
this.projectStore.incrementUseCount(memory.learning.id);
} else {
@@ -325,7 +308,6 @@ export class MemoryInjector {
}
}
// Format the content
const formattedContent = this.formatMemories(selected, opts.disclosureLevel || 'preview');
return {
@@ -350,7 +332,6 @@ export class MemoryInjector {
): Promise<InjectionResult> {
const result = await this.inject(options);
// Reformat for specific agent
result.formattedContent = this.formatForAgent(result.memories, agent, options.disclosureLevel);
return result;
@@ -381,7 +362,6 @@ export class MemoryInjector {
switch (level) {
case 'summary':
// Just title and tags (already shown above)
break;
case 'preview':
lines.push(learning.content.slice(0, 200) + (learning.content.length > 200 ? '...' : ''));
-20
View File
@@ -8,10 +8,6 @@ export class MemoryIndexStore {
private data: MemoryIndex | null = null;
constructor(basePath: string, _isGlobal = false) {
// Both global and project use .skillkit subdirectory
// Global: ~/.skillkit/memory/index.yaml (basePath = homedir())
// Project: <projectPath>/.skillkit/memory/index.yaml (basePath = projectPath)
// Note: _isGlobal kept for API compatibility but basePath determines the actual path
this.filePath = join(basePath, '.skillkit', 'memory', 'index.yaml');
}
@@ -58,7 +54,6 @@ export class MemoryIndexStore {
}
private extractKeywords(text: string): string[] {
// Extract meaningful keywords from text
const stopWords = new Set([
'a', 'an', 'the', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
'of', 'with', 'by', 'from', 'is', 'are', 'was', 'were', 'be', 'been',
@@ -79,12 +74,10 @@ export class MemoryIndexStore {
indexLearning(learning: Learning): void {
const data = this.load();
// Extract keywords from title and content
const titleKeywords = this.extractKeywords(learning.title);
const contentKeywords = this.extractKeywords(learning.content);
const allKeywords = [...new Set([...titleKeywords, ...contentKeywords])];
// Index by keywords
for (const keyword of allKeywords) {
if (!data.entries[keyword]) {
data.entries[keyword] = [];
@@ -94,7 +87,6 @@ export class MemoryIndexStore {
}
}
// Index by tags
for (const tag of learning.tags) {
const normalizedTag = tag.toLowerCase();
if (!data.tags[normalizedTag]) {
@@ -105,7 +97,6 @@ export class MemoryIndexStore {
}
}
// Index by frameworks if present
if (learning.frameworks) {
for (const framework of learning.frameworks) {
const normalizedFw = framework.toLowerCase();
@@ -124,7 +115,6 @@ export class MemoryIndexStore {
removeLearning(learningId: string): void {
const data = this.load();
// Remove from keyword entries
for (const keyword of Object.keys(data.entries)) {
data.entries[keyword] = data.entries[keyword].filter((id) => id !== learningId);
if (data.entries[keyword].length === 0) {
@@ -132,7 +122,6 @@ export class MemoryIndexStore {
}
}
// Remove from tags
for (const tag of Object.keys(data.tags)) {
data.tags[tag] = data.tags[tag].filter((id) => id !== learningId);
if (data.tags[tag].length === 0) {
@@ -149,20 +138,16 @@ export class MemoryIndexStore {
if (keywords.length === 0) return [];
// Find IDs that match any keyword
const matchCounts = new Map<string, number>();
for (const keyword of keywords) {
// Exact match
if (data.entries[keyword]) {
for (const id of data.entries[keyword]) {
matchCounts.set(id, (matchCounts.get(id) || 0) + 2);
}
}
// Partial match (keyword is substring of indexed word, but not exact match)
for (const [indexed, ids] of Object.entries(data.entries)) {
// Skip exact matches - they're already counted above with higher weight
if (indexed === keyword) continue;
if (indexed.includes(keyword) || keyword.includes(indexed)) {
for (const id of ids) {
@@ -172,7 +157,6 @@ export class MemoryIndexStore {
}
}
// Sort by match count (most matches first)
return [...matchCounts.entries()]
.sort((a, b) => b[1] - a[1])
.map(([id]) => id);
@@ -192,7 +176,6 @@ export class MemoryIndexStore {
}
}
// Sort by match count
return [...matchCounts.entries()]
.sort((a, b) => b[1] - a[1])
.map(([id]) => id);
@@ -210,7 +193,6 @@ export class MemoryIndexStore {
return tagResults;
}
// Combine results, prioritizing items that match both
const keywordSet = new Set(keywordResults);
const tagSet = new Set(tagResults);
@@ -250,10 +232,8 @@ export class MemoryIndexStore {
}
rebuildIndex(learnings: Learning[]): void {
// Clear existing index
this.data = this.createEmpty();
// Re-index all learnings
for (const learning of learnings) {
this.indexLearning(learning);
}
+92 -1
View File
@@ -10,14 +10,37 @@ import type {
} from './types.js';
import type { AgentType } from '../types.js';
/**
* Auto-compression callback type
*/
export type AutoCompressCallback = (observations: Observation[]) => Promise<void>;
/**
* Observation store options
*/
export interface ObservationStoreOptions {
compressionThreshold?: number;
autoCompress?: boolean;
onThresholdReached?: AutoCompressCallback;
}
export class ObservationStore {
private readonly filePath: string;
private readonly projectPath: string;
private data: ObservationStoreData | null = null;
private sessionId: string;
private compressionThreshold: number;
private autoCompress: boolean;
private onThresholdReached?: AutoCompressCallback;
private compressionInProgress = false;
constructor(projectPath: string, sessionId?: string) {
constructor(projectPath: string, sessionId?: string, options: ObservationStoreOptions = {}) {
this.projectPath = projectPath;
this.filePath = join(projectPath, '.skillkit', 'memory', 'observations.yaml');
this.sessionId = sessionId || randomUUID();
this.compressionThreshold = options.compressionThreshold ?? 50;
this.autoCompress = options.autoCompress ?? true;
this.onThresholdReached = options.onThresholdReached;
}
private ensureDir(): void {
@@ -83,9 +106,77 @@ export class ObservationStore {
data.observations.push(observation);
this.save();
void this.checkAutoCompression().catch(() => {
// Silently ignore auto-compression errors to avoid disrupting add()
});
return observation;
}
/**
* Check if auto-compression should trigger
*/
private async checkAutoCompression(): Promise<void> {
if (!this.autoCompress || this.compressionInProgress) return;
if (!this.onThresholdReached) return;
const count = this.count();
if (count >= this.compressionThreshold) {
this.compressionInProgress = true;
try {
const observations = this.getAll();
await this.onThresholdReached(observations);
} finally {
this.compressionInProgress = false;
}
}
}
/**
* Set auto-compression callback
*/
setAutoCompressCallback(callback: AutoCompressCallback): void {
this.onThresholdReached = callback;
}
/**
* Enable/disable auto-compression
*/
setAutoCompress(enabled: boolean): void {
this.autoCompress = enabled;
}
/**
* Set compression threshold
*/
setCompressionThreshold(threshold: number): void {
if (threshold < 1 || !Number.isInteger(threshold)) {
throw new Error('Compression threshold must be a positive integer');
}
this.compressionThreshold = threshold;
}
/**
* Get compression threshold
*/
getCompressionThreshold(): number {
return this.compressionThreshold;
}
/**
* Check if threshold is reached
*/
isThresholdReached(): boolean {
return this.count() >= this.compressionThreshold;
}
/**
* Get project path
*/
getProjectPath(): string {
return this.projectPath;
}
getAll(): Observation[] {
return this.load().observations;
}
+1 -26
View File
@@ -118,26 +118,18 @@ export class MemoryObserver {
* Observe an event and potentially store it
*/
observe(event: ObservableEvent): Observation | null {
// Check if we should capture this event type
if (!this.shouldCapture(event)) {
return null;
}
// Classify the event into an observation type
const observationType = this.classifyEvent(event);
// Extract content from the event
const content = this.extractContent(event);
// Score relevance
const relevance = this.scoreRelevance(event);
// Check minimum relevance threshold
if (relevance < this.config.minRelevance) {
return null;
}
// Store the observation
return this.store.add(observationType, content, this.currentAgent, relevance);
}
@@ -243,7 +235,6 @@ export class MemoryObserver {
context,
};
// Store pending error for potential solution matching
const errorKey = this.generateErrorKey(error);
this.pendingErrors.set(errorKey, event);
@@ -263,7 +254,6 @@ export class MemoryObserver {
error: relatedError,
};
// If we can match this to a pending error, increase relevance
if (relatedError) {
const errorKey = this.generateErrorKey(relatedError);
this.pendingErrors.delete(errorKey);
@@ -393,7 +383,6 @@ export class MemoryObserver {
content.solution = event.output;
}
// Generate tags based on event
content.tags = this.generateTags(event);
return content;
@@ -462,15 +451,12 @@ export class MemoryObserver {
private generateTags(event: ObservableEvent): string[] {
const tags: string[] = [];
// Add event type as tag
tags.push(event.type.replace(/_/g, '-'));
// Add skill name if present
if (event.skillName) {
tags.push(event.skillName.toLowerCase().replace(/[^a-z0-9-]/g, '-'));
}
// Add error-related tags
if (event.error) {
if (event.error.toLowerCase().includes('type')) tags.push('typescript');
if (event.error.toLowerCase().includes('import')) tags.push('imports');
@@ -480,7 +466,6 @@ export class MemoryObserver {
tags.push('async');
}
// Add file-related tags
if (event.files) {
for (const file of event.files) {
if (file.endsWith('.ts') || file.endsWith('.tsx')) tags.push('typescript');
@@ -498,16 +483,13 @@ export class MemoryObserver {
* Score relevance of event
*/
private scoreRelevance(event: ObservableEvent): number {
// Use custom scorer if provided
if (this.config.relevanceScorer) {
return this.config.relevanceScorer(event);
}
// Default relevance scoring
let score = 50; // Base score
let score = 50;
switch (event.type) {
// High relevance events
case 'error_encountered':
case 'task_failed':
score = 85;
@@ -515,7 +497,6 @@ export class MemoryObserver {
case 'solution_applied':
score = 90;
// Bonus if it matches a pending error
if (event.error) {
const errorKey = this.generateErrorKey(event.error);
if (this.pendingErrors.has(errorKey)) {
@@ -532,10 +513,8 @@ export class MemoryObserver {
score = 80;
break;
// Medium relevance events
case 'file_modified':
score = 60;
// More files = higher relevance
if (event.files && event.files.length > 3) {
score = 70;
}
@@ -550,7 +529,6 @@ export class MemoryObserver {
score = 50;
break;
// Lower relevance events
case 'task_start':
score = 30;
break;
@@ -568,7 +546,6 @@ export class MemoryObserver {
score = 50;
}
// Adjust based on content richness
if (event.context && event.context.length > 100) {
score += 5;
}
@@ -577,7 +554,6 @@ export class MemoryObserver {
score += 5;
}
// Cap at 100
return Math.min(score, 100);
}
@@ -585,7 +561,6 @@ export class MemoryObserver {
* Generate a key for matching errors to solutions
*/
private generateErrorKey(error: string): string {
// Normalize error string for matching
return error
.toLowerCase()
.replace(/[0-9]+/g, 'N') // Replace numbers
@@ -0,0 +1,458 @@
/**
* Progressive Disclosure System
*
* Implements 3-layer token-optimized retrieval for efficient context usage:
* - Layer 1: Index (titles, timestamps, IDs) - ~50-100 tokens
* - Layer 2: Timeline (context around observations) - ~200 tokens
* - Layer 3: Details (full content) - ~500-1000 tokens
*/
import type { Learning } from './types.js';
import { LearningStore } from './learning-store.js';
/**
* Index entry (Layer 1)
* Minimal information for fast scanning
*/
export interface IndexEntry {
id: string;
title: string;
timestamp: string;
tags: string[];
scope: 'project' | 'global';
effectiveness?: number;
useCount: number;
}
/**
* Timeline entry (Layer 2)
* Context around the learning with activity timeline
*/
export interface TimelineEntry extends IndexEntry {
excerpt: string;
frameworks?: string[];
patterns?: string[];
sourceCount: number;
lastUsed?: string;
activityTimeline?: ActivityPoint[];
}
/**
* Activity point for timeline
*/
export interface ActivityPoint {
timestamp: string;
type: 'created' | 'used' | 'updated' | 'rated';
description?: string;
}
/**
* Details entry (Layer 3)
* Full content with all metadata
*/
export interface DetailsEntry extends TimelineEntry {
content: string;
sourceObservations?: string[];
metadata?: Record<string, unknown>;
}
/**
* Progressive disclosure options
*/
export interface ProgressiveDisclosureOptions {
includeGlobal?: boolean;
minRelevance?: number;
maxResults?: number;
}
/**
* Token estimates per layer
*/
const TOKEN_ESTIMATES = {
index: 50,
timeline: 200,
details: 600,
};
/**
* Progressive Disclosure Manager
*
* Provides 3-layer retrieval for optimal token usage.
*/
export class ProgressiveDisclosureManager {
private projectStore: LearningStore;
private globalStore: LearningStore;
constructor(projectPath: string, projectName?: string) {
this.projectStore = new LearningStore('project', projectPath, projectName);
this.globalStore = new LearningStore('global');
}
/**
* Layer 1: Get index of all learnings
* Minimal tokens (~50-100 per entry)
*/
getIndex(options: ProgressiveDisclosureOptions = {}): IndexEntry[] {
const projectLearnings = this.projectStore.getAll();
const globalLearnings = options.includeGlobal ? this.globalStore.getAll() : [];
const allLearnings = [...projectLearnings, ...globalLearnings];
return allLearnings
.map((learning) => this.toIndexEntry(learning))
.sort((a, b) => {
const scoreA = (a.effectiveness ?? 50) + a.useCount * 5;
const scoreB = (b.effectiveness ?? 50) + b.useCount * 5;
return scoreB - scoreA;
})
.slice(0, options.maxResults ?? 50);
}
/**
* Layer 2: Get timeline entries for specific IDs
* Medium tokens (~200 per entry)
*/
getTimeline(ids: string[], options: ProgressiveDisclosureOptions = {}): TimelineEntry[] {
const entries: TimelineEntry[] = [];
for (const id of ids) {
let learning = this.projectStore.getById(id);
if (!learning && options.includeGlobal) {
learning = this.globalStore.getById(id);
}
if (learning) {
entries.push(this.toTimelineEntry(learning));
}
}
return entries.slice(0, options.maxResults ?? 20);
}
/**
* Layer 3: Get full details for specific IDs
* High tokens (~500-1000 per entry)
*/
getDetails(ids: string[], options: ProgressiveDisclosureOptions = {}): DetailsEntry[] {
const entries: DetailsEntry[] = [];
for (const id of ids) {
let learning = this.projectStore.getById(id);
let store = this.projectStore;
if (!learning && options.includeGlobal) {
learning = this.globalStore.getById(id);
store = this.globalStore;
}
if (learning) {
store.incrementUseCount(id);
entries.push(this.toDetailsEntry(learning));
}
}
return entries.slice(0, options.maxResults ?? 10);
}
/**
* Smart retrieval with automatic layer selection
* Uses minimum tokens needed to satisfy the query.
*
* Note: tokensUsed reflects cumulative cost of the retrieval operation
* (index lookup + any deeper layer fetches), not just the returned entries.
* This is intentional since progressive disclosure requires scanning
* the index first before fetching timeline/details.
*/
smartRetrieve(
query: string,
tokenBudget: number = 2000,
options: ProgressiveDisclosureOptions = {}
): {
layer: 1 | 2 | 3;
entries: IndexEntry[] | TimelineEntry[] | DetailsEntry[];
tokensUsed: number;
tokensRemaining: number;
} {
if (tokenBudget <= 0) {
return {
layer: 1,
entries: [],
tokensUsed: 0,
tokensRemaining: 0,
};
}
const index = this.getIndex(options);
if (index.length === 0) {
return {
layer: 1,
entries: [],
tokensUsed: 0,
tokensRemaining: tokenBudget,
};
}
const indexTokens = index.length * TOKEN_ESTIMATES.index;
if (tokenBudget < indexTokens) {
const maxEntries = Math.floor(tokenBudget / TOKEN_ESTIMATES.index);
const limitedIndex = index.slice(0, maxEntries);
return {
layer: 1,
entries: limitedIndex,
tokensUsed: limitedIndex.length * TOKEN_ESTIMATES.index,
tokensRemaining: tokenBudget - limitedIndex.length * TOKEN_ESTIMATES.index,
};
}
const relevantIds = this.findRelevantIds(index, query, options.minRelevance ?? 0);
if (relevantIds.length === 0) {
return {
layer: 1,
entries: index,
tokensUsed: indexTokens,
tokensRemaining: tokenBudget - indexTokens,
};
}
const remainingBudget = tokenBudget - indexTokens;
const maxTimelineEntries = Math.floor(remainingBudget / TOKEN_ESTIMATES.timeline);
if (maxTimelineEntries >= 1) {
const timelineIds = relevantIds.slice(0, Math.min(maxTimelineEntries, 10));
const timeline = this.getTimeline(timelineIds, options);
const timelineTokens = timeline.length * TOKEN_ESTIMATES.timeline;
const afterTimelineBudget = remainingBudget - timelineTokens;
const maxDetailsEntries = Math.floor(afterTimelineBudget / TOKEN_ESTIMATES.details);
if (maxDetailsEntries >= 1) {
const detailsIds = timelineIds.slice(0, Math.min(maxDetailsEntries, 5));
const details = this.getDetails(detailsIds, options);
const detailsTokens = details.length * TOKEN_ESTIMATES.details;
return {
layer: 3,
entries: details,
tokensUsed: indexTokens + timelineTokens + detailsTokens,
tokensRemaining: tokenBudget - (indexTokens + timelineTokens + detailsTokens),
};
}
return {
layer: 2,
entries: timeline,
tokensUsed: indexTokens + timelineTokens,
tokensRemaining: tokenBudget - (indexTokens + timelineTokens),
};
}
return {
layer: 1,
entries: index,
tokensUsed: indexTokens,
tokensRemaining: tokenBudget - indexTokens,
};
}
/**
* Estimate tokens for a given layer and count
*/
estimateTokens(layer: 1 | 2 | 3, count: number): number {
const estimate = {
1: TOKEN_ESTIMATES.index,
2: TOKEN_ESTIMATES.timeline,
3: TOKEN_ESTIMATES.details,
};
return estimate[layer] * count;
}
/**
* Format entries for injection
*/
formatForInjection(
entries: IndexEntry[] | TimelineEntry[] | DetailsEntry[],
layer: 1 | 2 | 3
): string {
if (entries.length === 0) return '';
const lines: string[] = ['<skillkit-memories>'];
switch (layer) {
case 1:
lines.push('<!-- Memory Index (summaries only) -->');
for (const entry of entries as IndexEntry[]) {
lines.push(`- [${entry.id.slice(0, 8)}] ${entry.title} (${entry.tags.join(', ')})`);
}
break;
case 2:
lines.push('<!-- Memory Timeline (with context) -->');
for (const entry of entries as TimelineEntry[]) {
lines.push(`## ${entry.title}`);
lines.push(`ID: ${entry.id.slice(0, 8)} | Tags: ${entry.tags.join(', ')}`);
if (entry.frameworks && entry.frameworks.length > 0) {
lines.push(`Frameworks: ${entry.frameworks.join(', ')}`);
}
lines.push('');
lines.push(entry.excerpt);
lines.push('');
}
break;
case 3:
lines.push('<!-- Memory Details (full content) -->');
for (const entry of entries as DetailsEntry[]) {
lines.push(`## ${entry.title}`);
lines.push(`ID: ${entry.id.slice(0, 8)} | Tags: ${entry.tags.join(', ')}`);
if (entry.frameworks && entry.frameworks.length > 0) {
lines.push(`Frameworks: ${entry.frameworks.join(', ')}`);
}
if (entry.patterns && entry.patterns.length > 0) {
lines.push(`Patterns: ${entry.patterns.join(', ')}`);
}
lines.push('');
lines.push(entry.content);
lines.push('');
}
break;
}
lines.push('</skillkit-memories>');
return lines.join('\n');
}
private toIndexEntry(learning: Learning): IndexEntry {
return {
id: learning.id,
title: learning.title,
timestamp: learning.updatedAt,
tags: learning.tags,
scope: learning.scope,
effectiveness: learning.effectiveness,
useCount: learning.useCount,
};
}
private toTimelineEntry(learning: Learning): TimelineEntry {
const timeline = this.buildActivityTimeline(learning);
return {
id: learning.id,
title: learning.title,
timestamp: learning.updatedAt,
tags: learning.tags,
scope: learning.scope,
effectiveness: learning.effectiveness,
useCount: learning.useCount,
excerpt: learning.content.slice(0, 200) + (learning.content.length > 200 ? '...' : ''),
frameworks: learning.frameworks,
patterns: learning.patterns,
sourceCount: learning.sourceObservations?.length ?? 0,
lastUsed: learning.lastUsed,
activityTimeline: timeline,
};
}
private toDetailsEntry(learning: Learning): DetailsEntry {
const timeline = this.buildActivityTimeline(learning);
return {
id: learning.id,
title: learning.title,
timestamp: learning.updatedAt,
tags: learning.tags,
scope: learning.scope,
effectiveness: learning.effectiveness,
useCount: learning.useCount,
excerpt: learning.content.slice(0, 200) + (learning.content.length > 200 ? '...' : ''),
frameworks: learning.frameworks,
patterns: learning.patterns,
sourceCount: learning.sourceObservations?.length ?? 0,
lastUsed: learning.lastUsed,
activityTimeline: timeline,
content: learning.content,
sourceObservations: learning.sourceObservations,
};
}
private buildActivityTimeline(learning: Learning): ActivityPoint[] {
const timeline: ActivityPoint[] = [];
timeline.push({
timestamp: learning.createdAt,
type: 'created',
description: `Learning created from ${learning.source}`,
});
if (learning.updatedAt !== learning.createdAt) {
timeline.push({
timestamp: learning.updatedAt,
type: 'updated',
});
}
if (learning.lastUsed) {
timeline.push({
timestamp: learning.lastUsed,
type: 'used',
description: `Used ${learning.useCount} times`,
});
}
if (learning.effectiveness !== undefined) {
timeline.push({
timestamp: learning.updatedAt,
type: 'rated',
description: `Effectiveness: ${learning.effectiveness}%`,
});
}
return timeline.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
}
private findRelevantIds(index: IndexEntry[], query: string, minRelevance: number = 0): string[] {
const queryWords = query.toLowerCase().split(/\s+/).filter((w) => w.length > 2);
const scored: Array<{ id: string; score: number }> = [];
for (const entry of index) {
let score = 0;
const titleWords = entry.title.toLowerCase().split(/\s+/);
for (const qw of queryWords) {
if (titleWords.some((tw) => tw.includes(qw))) {
score += 10;
}
}
const tags = entry.tags.map((t) => t.toLowerCase());
for (const qw of queryWords) {
if (tags.includes(qw)) {
score += 20;
}
}
score += (entry.effectiveness ?? 50) / 10;
score += Math.min(entry.useCount * 2, 20);
if (score >= minRelevance) {
scored.push({ id: entry.id, score });
}
}
return scored
.sort((a, b) => b.score - a.score)
.map((s) => s.id);
}
}
/**
* Create a progressive disclosure manager
*/
export function createProgressiveDisclosureManager(
projectPath: string,
projectName?: string
): ProgressiveDisclosureManager {
return new ProgressiveDisclosureManager(projectPath, projectName);
}