@aitytech/agentkits-memory 1.0.0

package/README.md

@@ -0,0 +1,250 @@
+# @agentkits/memory
+
+Project-scoped memory system for AgentKits with SQLite storage and optional HNSW vector search.
+
+## Features
+
+- **Project-Scoped Storage**: Memory is stored in `.claude/memory/memory.db` within your project
+- **SQLite + WASM**: Cross-platform compatibility (Windows, macOS, Linux)
+- **Optional Vector Search**: HNSW indexing for semantic similarity search
+- **Session Tracking**: Track Claude Code sessions with checkpoints
+- **Migration Support**: Migrate from existing `.claude/memory/*.md` files
+- **Backward Compatible**: Export to markdown for git-friendly backups
+
+## Installation
+
+```bash
+npm install @agentkits/memory
+# or
+pnpm add @agentkits/memory
+```
+
+## Quick Start
+
+```typescript
+import { ProjectMemoryService } from '@agentkits/memory';
+
+// Initialize memory for current project
+const memory = new ProjectMemoryService('.claude/memory');
+await memory.initialize();
+
+// Store an entry
+await memory.storeEntry({
+  key: 'auth-pattern',
+  content: 'Use JWT with refresh tokens for authentication',
+  namespace: 'patterns',
+  tags: ['auth', 'security'],
+});
+
+// Query entries
+const patterns = await memory.query({
+  type: 'hybrid',
+  namespace: 'patterns',
+  tags: ['auth'],
+  limit: 10,
+});
+
+// Get by key
+const entry = await memory.getByKey('patterns', 'auth-pattern');
+```
+
+## Session Management
+
+```typescript
+// Start a new session
+await memory.startSession();
+
+// Create checkpoints during work
+await memory.checkpoint('Completed authentication setup');
+await memory.checkpoint('Added user registration');
+
+// End session with summary
+await memory.endSession('Successfully implemented auth flow');
+
+// Get recent sessions
+const sessions = await memory.getRecentSessions(5);
+```
+
+## Migration from Markdown
+
+```typescript
+// Migrate existing .claude/memory/*.md files
+const result = await memory.migrateFromMarkdown();
+console.log(result.summary);
+// Output: "Migrated 24/24 entries"
+```
+
+## Semantic Search (Optional)
+
+```typescript
+import { createEmbeddingMemory } from '@agentkits/memory';
+
+// Create memory with embedding support
+const memory = createEmbeddingMemory(
+  '.claude/memory',
+  async (text) => {
+    // Your embedding function (e.g., OpenAI, local model)
+    return await embeddings.embed(text);
+  },
+  384 // dimensions
+);
+
+await memory.initialize();
+
+// Semantic search
+const similar = await memory.semanticSearch('how to authenticate users', 5);
+```
+
+## Export to Markdown
+
+```typescript
+// Export namespace to markdown (for git)
+await memory.exportToMarkdown('patterns');
+// Creates: .claude/memory/patterns.md
+
+// Export all namespaces
+const files = await memory.exportAllToMarkdown();
+```
+
+## Default Namespaces
+
+The memory system uses these default namespaces (matching existing `.md` file structure):
+
+| Namespace | Type | Purpose |
+|-----------|------|---------|
+| `context` | semantic | Project context and facts |
+| `active-context` | episodic | Current work focus |
+| `session-state` | episodic | Session handoff notes |
+| `progress` | episodic | Feature tracking |
+| `patterns` | semantic | Reusable code patterns |
+| `decisions` | procedural | ADRs and decisions |
+| `errors` | procedural | Error solutions |
+
+## API Reference
+
+### ProjectMemoryService
+
+#### Configuration
+
+```typescript
+interface ProjectMemoryConfig {
+  baseDir: string;              // Default: '.claude/memory'
+  dbFilename: string;           // Default: 'memory.db'
+  enableVectorIndex: boolean;   // Default: false
+  dimensions: number;           // Default: 384
+  embeddingGenerator?: EmbeddingGenerator;
+  cacheEnabled: boolean;        // Default: true
+  cacheSize: number;            // Default: 1000
+  cacheTtl: number;             // Default: 300000 (5 min)
+  autoPersistInterval: number;  // Default: 10000 (10 sec)
+  maxEntries: number;           // Default: 100000
+  verbose: boolean;             // Default: false
+}
+```
+
+#### Methods
+
+| Method | Description |
+|--------|-------------|
+| `initialize()` | Initialize the memory service |
+| `shutdown()` | Shutdown and persist changes |
+| `store(entry)` | Store a memory entry |
+| `storeEntry(input)` | Store from simple input |
+| `get(id)` | Get entry by ID |
+| `getByKey(namespace, key)` | Get entry by namespace and key |
+| `update(id, update)` | Update an entry |
+| `delete(id)` | Delete an entry |
+| `query(query)` | Query entries with filters |
+| `search(embedding, options)` | Vector similarity search |
+| `semanticSearch(content, k)` | Search by content string |
+| `count(namespace?)` | Count entries |
+| `listNamespaces()` | List all namespaces |
+| `clearNamespace(namespace)` | Clear a namespace |
+| `startSession()` | Start new session |
+| `checkpoint(description)` | Create checkpoint |
+| `endSession(summary?)` | End current session |
+| `migrateFromMarkdown()` | Migrate from .md files |
+| `exportToMarkdown(namespace)` | Export to markdown |
+| `getStats()` | Get statistics |
+| `healthCheck()` | Health check |
+
+## Architecture
+
+```
+.claude/memory/
+├── memory.db          # SQLite database (primary storage)
+├── memory.db-wal      # Write-ahead log (temp)
+└── exports/           # Optional markdown exports
+    ├── patterns.md
+    ├── decisions.md
+    └── ...
+```
+
+## Performance
+
+| Operation | Time |
+|-----------|------|
+| Store entry | <5ms |
+| Get by ID | <2ms (cached: <0.1ms) |
+| Query (100 results) | <10ms |
+| Vector search (10k entries) | <5ms (with HNSW) |
+| Migration (100 files) | <2s |
+
+## Claude Code Hooks (Auto-Capture)
+
+The memory package includes a lightweight hook system for automatically capturing Claude Code sessions.
+
+### Quick Setup
+
+1. Install the package globally or in your project:
+```bash
+npm install -g @agentkits/memory
+# or
+npm install @agentkits/memory
+```
+
+2. Copy the hooks configuration to your project:
+```bash
+cp node_modules/@agentkits/memory/hooks.json .claude/hooks.json
+```
+
+3. Claude Code will now automatically:
+   - Inject previous session context on start
+   - Track all tool usage during the session
+   - Generate session summaries on exit
+
+### Hook Events
+
+| Event | Trigger | Action |
+|-------|---------|--------|
+| `context` | SessionStart | Injects memory context |
+| `session-init` | UserPromptSubmit | Initializes session record |
+| `observation` | PostToolUse | Captures tool usage |
+| `summarize` | Stop | Generates session summary |
+
+### Manual Hook Usage
+
+```typescript
+import { createContextHook, createObservationHook } from '@agentkits/memory/hooks';
+
+// Create hook handlers
+const contextHook = createContextHook(process.cwd());
+const observationHook = createObservationHook(process.cwd());
+
+// Execute hooks
+const result = await contextHook.execute(input);
+```
+
+### Database Location
+
+Hook data is stored in `.claude/memory/hooks.db` within your project directory.
+
+### Skipped Tools
+
+Internal tools that are not captured:
+- `TodoWrite`, `TodoRead`
+- `AskFollowupQuestion`, `AttemptCompletion`
+
+## License
+
+MIT - Based on claude-flow memory system (AGPL-3.0)

package/dist/cache-manager.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Cache Manager
+ *
+ * High-performance LRU cache with TTL support, memory pressure handling,
+ * and write-through caching for the unified memory system.
+ *
+ * @module @agentkits/memory/cache-manager
+ */
+import { EventEmitter } from 'node:events';
+import { CacheConfig, CacheStats, MemoryEntry } from './types.js';
+/**
+ * High-performance LRU Cache with TTL support
+ *
+ * Features:
+ * - O(1) get, set, delete operations
+ * - LRU eviction policy
+ * - TTL-based expiration
+ * - Memory pressure handling
+ * - Write-through caching support
+ * - Performance statistics
+ */
+export declare class CacheManager<T = MemoryEntry> extends EventEmitter {
+    private config;
+    private cache;
+    private head;
+    private tail;
+    private currentMemory;
+    private stats;
+    private cleanupInterval;
+    constructor(config?: Partial<CacheConfig>);
+    /**
+     * Get a value from the cache
+     */
+    get(key: string): T | null;
+    /**
+     * Set a value in the cache
+     */
+    set(key: string, data: T, ttl?: number): void;
+    /**
+     * Delete a value from the cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Check if a key exists in the cache (without affecting LRU order)
+     */
+    has(key: string): boolean;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Get all keys in the cache
+     */
+    keys(): string[];
+    /**
+     * Get the size of the cache
+     */
+    get size(): number;
+    /**
+     * Prefetch multiple keys in a single batch
+     */
+    prefetch(keys: string[], loader: (keys: string[]) => Promise<Map<string, T>>, ttl?: number): Promise<void>;
+    /**
+     * Get or set pattern - get from cache or load and cache
+     */
+    getOrSet(key: string, loader: () => Promise<T>, ttl?: number): Promise<T>;
+    /**
+     * Warm the cache with initial data
+     */
+    warmUp(entries: Array<{
+        key: string;
+        data: T;
+        ttl?: number;
+    }>): void;
+    /**
+     * Invalidate entries matching a pattern
+     */
+    invalidatePattern(pattern: string | RegExp): number;
+    /**
+     * Shutdown the cache manager
+     */
+    shutdown(): void;
+    private mergeConfig;
+    private isExpired;
+    private estimateSize;
+    private addToFront;
+    private removeNode;
+    private moveToFront;
+    private evictLRU;
+    private startCleanupTimer;
+    private cleanupExpired;
+}
+/**
+ * Multi-layer cache with L1 (memory) and L2 (storage) tiers
+ */
+export declare class TieredCacheManager<T = MemoryEntry> extends EventEmitter {
+    private l1Cache;
+    private l2Loader;
+    private l2Writer;
+    constructor(l1Config?: Partial<CacheConfig>, l2Options?: {
+        loader: (key: string) => Promise<T | null>;
+        writer?: (key: string, value: T) => Promise<void>;
+    });
+    /**
+     * Get from tiered cache
+     */
+    get(key: string): Promise<T | null>;
+    /**
+     * Set in tiered cache
+     */
+    set(key: string, value: T, ttl?: number): Promise<void>;
+    /**
+     * Delete from tiered cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Get L1 cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Clear L1 cache
+     */
+    clear(): void;
+    /**
+     * Shutdown tiered cache
+     */
+    shutdown(): void;
+}
+export default CacheManager;
+//# sourceMappingURL=cache-manager.d.ts.map

package/dist/cache-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-manager.d.ts","sourceRoot":"","sources":["../src/cache-manager.ts"],"names":[],"mappings":"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"}