@aitytech/agentkits-memory 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,481 @@
+/**
+ * Project-Scoped Memory Types
+ *
+ * Type definitions for the AgentKits memory system.
+ * Designed for project-level memory stored in .claude/memory/
+ *
+ * @module @agentkits/memory/types
+ */
+/**
+ * Memory entry type classification (matches existing .claude/memory/*.md structure)
+ */
+export type MemoryType = 'episodic' | 'semantic' | 'procedural' | 'working' | 'cache';
+/**
+ * Access level for memory entries
+ */
+export type AccessLevel = 'private' | 'project' | 'shared';
+/**
+ * Distance metrics for vector similarity search
+ */
+export type DistanceMetric = 'cosine' | 'euclidean' | 'dot' | 'manhattan';
+/**
+ * Core memory entry structure with optional vector embedding
+ */
+export interface MemoryEntry {
+    /** Unique identifier */
+    id: string;
+    /** Human-readable key for retrieval (e.g., 'active-context', 'auth-pattern') */
+    key: string;
+    /** Actual content of the memory */
+    content: string;
+    /** Vector embedding for semantic search (Float32Array for efficiency) */
+    embedding?: Float32Array;
+    /** Type of memory */
+    type: MemoryType;
+    /** Namespace for organization (maps to old .md file categories) */
+    namespace: string;
+    /** Tags for categorization and filtering */
+    tags: string[];
+    /** Additional metadata */
+    metadata: Record<string, unknown>;
+    /** Session ID that created this entry */
+    sessionId?: string;
+    /** Owner ID for multi-user scenarios */
+    ownerId?: string;
+    /** Access level */
+    accessLevel: AccessLevel;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Last update timestamp */
+    updatedAt: number;
+    /** Expiration timestamp (optional) */
+    expiresAt?: number;
+    /** Version number for optimistic locking */
+    version: number;
+    /** References to other memory entries */
+    references: string[];
+    /** Access count for usage tracking */
+    accessCount: number;
+    /** Last access timestamp */
+    lastAccessedAt: number;
+}
+/**
+ * Input for creating a new memory entry
+ */
+export interface MemoryEntryInput {
+    key: string;
+    content: string;
+    type?: MemoryType;
+    namespace?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    sessionId?: string;
+    accessLevel?: AccessLevel;
+    expiresAt?: number;
+    references?: string[];
+}
+/**
+ * Partial update for a memory entry
+ */
+export interface MemoryEntryUpdate {
+    content?: string;
+    tags?: string[];
+    metadata?: Record<string, unknown>;
+    accessLevel?: AccessLevel;
+    expiresAt?: number;
+    references?: string[];
+}
+/**
+ * Query type for memory retrieval
+ */
+export type QueryType = 'semantic' | 'exact' | 'prefix' | 'tag' | 'hybrid';
+/**
+ * Memory query specification
+ */
+export interface MemoryQuery {
+    /** Type of query to perform */
+    type: QueryType;
+    /** Content for semantic search (will be embedded) */
+    content?: string;
+    /** Pre-computed embedding for semantic search */
+    embedding?: Float32Array;
+    /** Exact key to match */
+    key?: string;
+    /** Key prefix to match */
+    keyPrefix?: string;
+    /** Namespace filter */
+    namespace?: string;
+    /** Tag filters (entries must have all specified tags) */
+    tags?: string[];
+    /** Memory type filter */
+    memoryType?: MemoryType;
+    /** Session ID filter */
+    sessionId?: string;
+    /** Owner ID filter */
+    ownerId?: string;
+    /** Access level filter */
+    accessLevel?: AccessLevel;
+    /** Metadata filters */
+    metadata?: Record<string, unknown>;
+    /** Time range filters */
+    createdAfter?: number;
+    createdBefore?: number;
+    updatedAfter?: number;
+    updatedBefore?: number;
+    /** Maximum number of results */
+    limit: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Minimum similarity threshold (0-1) for semantic search */
+    threshold?: number;
+    /** Include expired entries */
+    includeExpired?: boolean;
+    /** Distance metric for semantic search */
+    distanceMetric?: DistanceMetric;
+}
+/**
+ * Search result with similarity score
+ */
+export interface SearchResult {
+    /** The memory entry */
+    entry: MemoryEntry;
+    /** Similarity score (0-1, higher is better) */
+    score: number;
+    /** Distance from query vector */
+    distance: number;
+}
+/**
+ * Search options for vector search
+ */
+export interface SearchOptions {
+    /** Number of results to return */
+    k: number;
+    /** Minimum similarity threshold (0-1) */
+    threshold?: number;
+    /** Distance metric */
+    metric?: DistanceMetric;
+    /** Additional filters to apply post-search */
+    filters?: Partial<MemoryQuery>;
+}
+/**
+ * Quantization type
+ */
+export type QuantizationType = 'scalar' | 'product' | 'binary' | 'none';
+/**
+ * Quantization configuration for vector compression
+ */
+export interface QuantizationConfig {
+    /** Enable quantization */
+    enabled: boolean;
+    /** Number of bits per dimension (default: 8) */
+    bits: number;
+    /** Quantization method */
+    method: 'scalar' | 'product';
+    /** Quantization type (alternative to method) */
+    type?: QuantizationType;
+    /** Number of subquantizers for product quantization */
+    subquantizers?: number;
+}
+/**
+ * HNSW index configuration
+ */
+export interface HNSWConfig {
+    /** Vector dimensions (e.g., 384 for local models, 1536 for OpenAI) */
+    dimensions: number;
+    /** Maximum number of connections per layer (default: 16) */
+    M: number;
+    /** Size of the dynamic candidate list during construction (default: 200) */
+    efConstruction: number;
+    /** Maximum elements the index can hold */
+    maxElements: number;
+    /** Distance metric */
+    metric: DistanceMetric;
+    /** Quantization configuration */
+    quantization?: QuantizationConfig;
+}
+/**
+ * HNSW index statistics
+ */
+export interface HNSWStats {
+    /** Total number of vectors in the index */
+    vectorCount: number;
+    /** Memory usage in bytes */
+    memoryUsage: number;
+    /** Average search time in milliseconds */
+    avgSearchTime: number;
+    /** Index build time in milliseconds */
+    buildTime: number;
+    /** Compression ratio if quantization is enabled */
+    compressionRatio?: number;
+}
+/**
+ * Memory backend interface for storage and retrieval
+ */
+export interface IMemoryBackend {
+    /** Initialize the backend */
+    initialize(): Promise<void>;
+    /** Shutdown the backend */
+    shutdown(): Promise<void>;
+    /** Store a memory entry */
+    store(entry: MemoryEntry): Promise<void>;
+    /** Retrieve a memory entry by ID */
+    get(id: string): Promise<MemoryEntry | null>;
+    /** Retrieve a memory entry by key within a namespace */
+    getByKey(namespace: string, key: string): Promise<MemoryEntry | null>;
+    /** Update a memory entry */
+    update(id: string, update: MemoryEntryUpdate): Promise<MemoryEntry | null>;
+    /** Delete a memory entry */
+    delete(id: string): Promise<boolean>;
+    /** Query memory entries */
+    query(query: MemoryQuery): Promise<MemoryEntry[]>;
+    /** Semantic vector search */
+    search(embedding: Float32Array, options: SearchOptions): Promise<SearchResult[]>;
+    /** Bulk insert entries */
+    bulkInsert(entries: MemoryEntry[]): Promise<void>;
+    /** Bulk delete entries */
+    bulkDelete(ids: string[]): Promise<number>;
+    /** Get entry count */
+    count(namespace?: string): Promise<number>;
+    /** List all namespaces */
+    listNamespaces(): Promise<string[]>;
+    /** Clear all entries in a namespace */
+    clearNamespace(namespace: string): Promise<number>;
+    /** Get backend statistics */
+    getStats(): Promise<BackendStats>;
+    /** Perform health check */
+    healthCheck(): Promise<HealthCheckResult>;
+}
+/**
+ * Backend statistics
+ */
+export interface BackendStats {
+    /** Total number of entries */
+    totalEntries: number;
+    /** Entries by namespace */
+    entriesByNamespace: Record<string, number>;
+    /** Entries by type */
+    entriesByType: Record<MemoryType, number>;
+    /** Total memory usage in bytes */
+    memoryUsage: number;
+    /** HNSW index statistics */
+    hnswStats?: HNSWStats;
+    /** Cache statistics */
+    cacheStats?: CacheStats;
+    /** Average query time in milliseconds */
+    avgQueryTime: number;
+    /** Average search time in milliseconds */
+    avgSearchTime: number;
+}
+/**
+ * Health check result
+ */
+export interface HealthCheckResult {
+    /** Overall health status */
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    /** Individual component health */
+    components: {
+        storage: ComponentHealth;
+        index: ComponentHealth;
+        cache: ComponentHealth;
+    };
+    /** Health check timestamp */
+    timestamp: number;
+    /** Any issues detected */
+    issues: string[];
+    /** Recommendations for improvement */
+    recommendations: string[];
+}
+/**
+ * Individual component health status
+ */
+export interface ComponentHealth {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    latency: number;
+    message?: string;
+}
+/**
+ * Cache configuration
+ */
+export interface CacheConfig {
+    /** Maximum number of entries in the cache */
+    maxSize: number;
+    /** Default TTL in milliseconds */
+    ttl: number;
+    /** Enable LRU eviction */
+    lruEnabled: boolean;
+    /** Maximum memory usage in bytes */
+    maxMemory?: number;
+    /** Enable write-through caching (write to backend immediately) */
+    writeThrough?: boolean;
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+    /** Number of entries in cache */
+    size: number;
+    /** Cache hit rate (0-1) */
+    hitRate: number;
+    /** Total cache hits */
+    hits: number;
+    /** Total cache misses */
+    misses: number;
+    /** Total evictions */
+    evictions: number;
+    /** Memory usage in bytes */
+    memoryUsage: number;
+}
+/**
+ * Cached entry wrapper
+ */
+export interface CachedEntry<T> {
+    /** The cached data */
+    data: T;
+    /** When the entry was cached */
+    cachedAt: number;
+    /** When the entry expires */
+    expiresAt: number;
+    /** Last access timestamp */
+    lastAccessedAt: number;
+    /** Access count */
+    accessCount: number;
+}
+/**
+ * Migration source type
+ */
+export type MigrationSource = 'markdown' | 'json' | 'sqlite';
+/**
+ * Migration configuration
+ */
+export interface MigrationConfig {
+    /** Source backend type */
+    source: MigrationSource;
+    /** Source path or connection string */
+    sourcePath: string;
+    /** Batch size for migration */
+    batchSize: number;
+    /** Generate embeddings during migration */
+    generateEmbeddings: boolean;
+    /** Validate data during migration */
+    validateData: boolean;
+    /** Continue on error */
+    continueOnError: boolean;
+    /** Namespace mapping */
+    namespaceMapping?: Record<string, string>;
+    /** Type mapping */
+    typeMapping?: Record<string, MemoryType>;
+}
+/**
+ * Migration progress
+ */
+export interface MigrationProgress {
+    /** Total entries to migrate */
+    total: number;
+    /** Entries migrated so far */
+    migrated: number;
+    /** Entries failed */
+    failed: number;
+    /** Entries skipped */
+    skipped: number;
+    /** Progress percentage (0-100) */
+    percentage: number;
+    /** Errors encountered */
+    errors: MigrationError[];
+}
+/**
+ * Migration error
+ */
+export interface MigrationError {
+    /** Entry ID or key that failed */
+    entryId: string;
+    /** Error message */
+    message: string;
+    /** Error code */
+    code: string;
+    /** Whether the error is recoverable */
+    recoverable: boolean;
+}
+/**
+ * Migration result
+ */
+export interface MigrationResult {
+    /** Whether migration completed successfully */
+    success: boolean;
+    /** Final progress state */
+    progress: MigrationProgress;
+    /** Total time taken in milliseconds */
+    duration: number;
+    /** Summary message */
+    summary: string;
+}
+/**
+ * Session information for tracking Claude Code sessions
+ */
+export interface SessionInfo {
+    /** Session ID */
+    id: string;
+    /** Session start time */
+    startedAt: number;
+    /** Session end time (if ended) */
+    endedAt?: number;
+    /** Summary of work done */
+    summary?: string;
+    /** Status */
+    status: 'active' | 'completed' | 'abandoned';
+    /** Last checkpoint */
+    lastCheckpoint?: string;
+}
+/**
+ * Memory event types for index operations
+ */
+export type MemoryEventType = 'insert' | 'update' | 'delete' | 'search' | 'rebuild' | 'resize';
+/**
+ * Memory event for tracking index operations
+ */
+export interface MemoryEvent {
+    /** Event type */
+    type: MemoryEventType;
+    /** Entry ID (if applicable) */
+    entryId?: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Additional event data */
+    data?: Record<string, unknown>;
+}
+/**
+ * Handler function for memory events
+ */
+export type MemoryEventHandler = (event: MemoryEvent) => void | Promise<void>;
+/**
+ * Embedding generator function type
+ */
+export type EmbeddingGenerator = (content: string) => Promise<Float32Array>;
+/**
+ * Generates a unique memory ID
+ */
+export declare function generateMemoryId(): string;
+/**
+ * Generates a unique session ID
+ */
+export declare function generateSessionId(): string;
+/**
+ * Creates a default memory entry
+ */
+export declare function createDefaultEntry(input: MemoryEntryInput): MemoryEntry;
+/**
+ * Default namespaces matching existing .claude/memory/*.md structure
+ */
+export declare const DEFAULT_NAMESPACES: {
+    readonly CONTEXT: "context";
+    readonly ACTIVE: "active-context";
+    readonly SESSION: "session-state";
+    readonly PROGRESS: "progress";
+    readonly PATTERNS: "patterns";
+    readonly DECISIONS: "decisions";
+    readonly ERRORS: "errors";
+};
+/**
+ * Maps namespace to memory type
+ */
+export declare const NAMESPACE_TYPE_MAP: Record<string, MemoryType>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,73 @@
+/**
+ * Project-Scoped Memory Types
+ *
+ * Type definitions for the AgentKits memory system.
+ * Designed for project-level memory stored in .claude/memory/
+ *
+ * @module @agentkits/memory/types
+ */
+/**
+ * Generates a unique memory ID
+ */
+export function generateMemoryId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 10);
+    return `mem_${timestamp}_${random}`;
+}
+/**
+ * Generates a unique session ID
+ */
+export function generateSessionId() {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 6);
+    return `ses_${timestamp}_${random}`;
+}
+/**
+ * Creates a default memory entry
+ */
+export function createDefaultEntry(input) {
+    const now = Date.now();
+    return {
+        id: generateMemoryId(),
+        key: input.key,
+        content: input.content,
+        type: input.type || 'semantic',
+        namespace: input.namespace || 'default',
+        tags: input.tags || [],
+        metadata: input.metadata || {},
+        sessionId: input.sessionId,
+        accessLevel: input.accessLevel || 'project',
+        createdAt: now,
+        updatedAt: now,
+        expiresAt: input.expiresAt,
+        version: 1,
+        references: input.references || [],
+        accessCount: 0,
+        lastAccessedAt: now,
+    };
+}
+/**
+ * Default namespaces matching existing .claude/memory/*.md structure
+ */
+export const DEFAULT_NAMESPACES = {
+    CONTEXT: 'context', // project-context.md
+    ACTIVE: 'active-context', // active-context.md
+    SESSION: 'session-state', // session-state.md
+    PROGRESS: 'progress', // progress.md
+    PATTERNS: 'patterns', // patterns.md
+    DECISIONS: 'decisions', // decisions.md
+    ERRORS: 'errors', // errors.md
+};
+/**
+ * Maps namespace to memory type
+ */
+export const NAMESPACE_TYPE_MAP = {
+    [DEFAULT_NAMESPACES.CONTEXT]: 'semantic',
+    [DEFAULT_NAMESPACES.ACTIVE]: 'episodic',
+    [DEFAULT_NAMESPACES.SESSION]: 'episodic',
+    [DEFAULT_NAMESPACES.PROGRESS]: 'episodic',
+    [DEFAULT_NAMESPACES.PATTERNS]: 'semantic',
+    [DEFAULT_NAMESPACES.DECISIONS]: 'procedural',
+    [DEFAULT_NAMESPACES.ERRORS]: 'procedural',
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgoBH;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC3D,OAAO,OAAO,SAAS,IAAI,MAAM,EAAE,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1D,OAAO,OAAO,SAAS,IAAI,MAAM,EAAE,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAuB;IACxD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,OAAO;QACL,EAAE,EAAE,gBAAgB,EAAE;QACtB,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,UAAU;QAC9B,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,SAAS;QACvC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE;QACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,EAAE;QAC9B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,SAAS;QAC3C,SAAS,EAAE,GAAG;QACd,SAAS,EAAE,GAAG;QACd,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,OAAO,EAAE,CAAC;QACV,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,EAAE;QAClC,WAAW,EAAE,CAAC;QACd,cAAc,EAAE,GAAG;KACpB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,OAAO,EAAE,SAAS,EAAY,qBAAqB;IACnD,MAAM,EAAE,gBAAgB,EAAM,oBAAoB;IAClD,OAAO,EAAE,eAAe,EAAM,mBAAmB;IACjD,QAAQ,EAAE,UAAU,EAAU,cAAc;IAC5C,QAAQ,EAAE,UAAU,EAAU,cAAc;IAC5C,SAAS,EAAE,WAAW,EAAQ,eAAe;IAC7C,MAAM,EAAE,QAAQ,EAAc,YAAY;CAClC,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAA+B;IAC5D,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,UAAU;IACxC,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,UAAU;IACvC,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,UAAU;IACxC,CAAC,kBAAkB,CAAC,QAAQ,CAAC,EAAE,UAAU;IACzC,CAAC,kBAAkB,CAAC,QAAQ,CAAC,EAAE,UAAU;IACzC,CAAC,kBAAkB,CAAC,SAAS,CAAC,EAAE,YAAY;IAC5C,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,YAAY;CAC1C,CAAC"}

package/hooks.json

@@ -0,0 +1,46 @@
+{
+  "_comment": "REFERENCE ONLY - These hooks are integrated into .claude/hooks/*.sh scripts",
+  "_usage": "The shell scripts call 'npx agentkits-memory-hook <command>' for database integration",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx agentkits-memory-hook context",
+            "_note": "Called by .claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx agentkits-memory-hook summarize",
+            "_note": "Called by .claude/hooks/on-stop.sh"
+          }
+        ]
+      }
+    ]
+  },
+  "cliCommands": {
+    "agentkits-memory-hook": {
+      "context": "Load context from database on session start",
+      "session-init": "Initialize session in database",
+      "observation": "Save tool observations to database",
+      "summarize": "Create session summary on stop"
+    },
+    "agentkits-memory-save": {
+      "description": "Save entry to database",
+      "usage": "--content=X --category=X --tags=X --importance=X --project-dir=X"
+    },
+    "agentkits-memory-viewer": {
+      "description": "View database contents",
+      "usage": "--stats | --list | --namespace=X | --json | --export"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@aitytech/agentkits-memory",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Project-scoped memory system for AgentKits with SQLite + HNSW vector search",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./hooks": "./dist/hooks/index.js",
+    "./mcp": "./dist/mcp/index.js",
+    "./*": "./dist/*.js"
+  },
+  "bin": {
+    "agentkits-memory-hook": "./dist/hooks/cli.js",
+    "agentkits-memory-server": "./dist/mcp/server.js",
+    "agentkits-memory-viewer": "./dist/cli/viewer.js",
+    "agentkits-memory-save": "./dist/cli/save.js",
+    "agentkits-memory-setup": "./dist/cli/setup.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"Memory lint pending\" && exit 0",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aitytech/agentkits-memory"
+  },
+  "homepage": "https://agentkits.net",
+  "author": "AityTech",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "sql.js": "^1.10.3"
+  },
+  "optionalDependencies": {
+    "better-sqlite3": "^11.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.11",
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "typescript": "^5.3.0",
+    "vitest": "^4.0.16"
+  },
+  "files": [
+    "dist",
+    "src",
+    "hooks.json"
+  ],
+  "keywords": [
+    "agentkits",
+    "memory",
+    "sqlite",
+    "vector-search",
+    "hnsw",
+    "claude-code",
+    "hooks"
+  ],
+  "license": "MIT"
+}