@danielsimonjr/memoryjs 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Anthropic, PBC (Original Memory MCP Server)
+Copyright (c) 2025-2026 Daniel Simon Jr. (Enhanced Knowledge Graph Library)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,266 @@
+# @danielsimonjr/memoryjs
+
+Core knowledge graph library for managing entities, relations, and observations with advanced search capabilities.
+
+## Features
+
+- **Entity Management**: Create, read, update, delete entities with observations
+- **Relation Management**: Connect entities with typed relationships
+- **Hierarchical Organization**: Parent-child entity nesting
+- **Multiple Storage Backends**: JSONL (default) or SQLite
+- **Advanced Search**: Basic, ranked (TF-IDF), boolean, fuzzy, semantic, and hybrid search
+- **Tag Management**: Tag aliasing, bulk operations
+- **Graph Algorithms**: Shortest path, centrality, connected components
+- **Import/Export**: JSON, CSV, GraphML formats with compression
+
+## Installation
+
+```bash
+npm install @danielsimonjr/memoryjs
+```
+
+## Quick Start
+
+```typescript
+import { ManagerContext } from '@danielsimonjr/memoryjs';
+
+// Initialize with JSONL storage (default)
+const ctx = new ManagerContext({
+  storagePath: './memory.jsonl'
+});
+
+// Create entities
+await ctx.entityManager.createEntities([
+  { name: 'TypeScript', entityType: 'language', observations: ['A typed superset of JavaScript'] },
+  { name: 'Node.js', entityType: 'runtime', observations: ['JavaScript runtime built on V8'] }
+]);
+
+// Create relations
+await ctx.relationManager.createRelations([
+  { from: 'TypeScript', to: 'Node.js', relationType: 'runs_on' }
+]);
+
+// Search entities
+const results = await ctx.searchManager.search('JavaScript');
+```
+
+## Storage Options
+
+### JSONL (Default)
+
+```typescript
+const ctx = new ManagerContext({
+  storagePath: './memory.jsonl'
+});
+```
+
+### SQLite
+
+```typescript
+const ctx = new ManagerContext({
+  storageType: 'sqlite',
+  storagePath: './memory.db'
+});
+```
+
+SQLite provides:
+- FTS5 full-text search with BM25 ranking
+- Referential integrity (ON DELETE CASCADE)
+- WAL mode for better concurrency
+- ACID transactions
+
+## Core Components
+
+### ManagerContext
+
+Central access point for all managers:
+
+```typescript
+ctx.entityManager    // Entity CRUD + hierarchy
+ctx.relationManager  // Relation management
+ctx.searchManager    // All search operations
+ctx.tagManager       // Tag aliases
+ctx.ioManager        // Import/export/backup
+ctx.graphTraversal   // Graph algorithms
+ctx.semanticSearch   // Vector similarity search (optional)
+```
+
+### Entity Structure
+
+```typescript
+interface Entity {
+  name: string;           // Unique identifier
+  entityType: string;     // Classification
+  observations: string[]; // Facts about the entity
+  parentId?: string;      // For hierarchy
+  tags?: string[];        // Categories
+  importance?: number;    // 0-10 scale
+  createdAt?: string;     // ISO 8601
+  lastModified?: string;
+}
+```
+
+### Relation Structure
+
+```typescript
+interface Relation {
+  from: string;          // Source entity name
+  to: string;            // Target entity name
+  relationType: string;  // Connection type
+}
+```
+
+## Search Capabilities
+
+### Basic Search
+
+```typescript
+// Find entities by name or observation content
+const results = await ctx.searchManager.search('TypeScript');
+```
+
+### Ranked Search (TF-IDF)
+
+```typescript
+// Get relevance-scored results
+const ranked = await ctx.searchManager.searchRanked('JavaScript runtime', { limit: 10 });
+```
+
+### Boolean Search
+
+```typescript
+// AND, OR, NOT operators
+const results = await ctx.searchManager.booleanSearch('TypeScript AND runtime');
+const excluded = await ctx.searchManager.booleanSearch('JavaScript NOT browser');
+```
+
+### Fuzzy Search
+
+```typescript
+// Typo-tolerant search
+const results = await ctx.searchManager.fuzzySearch('Typscript', { threshold: 0.7 });
+```
+
+### Hybrid Search
+
+Combines semantic (vector), lexical (TF-IDF), and symbolic (metadata) signals:
+
+```typescript
+const results = await ctx.searchManager.hybridSearch('programming concepts', {
+  weights: { semantic: 0.5, lexical: 0.3, symbolic: 0.2 },
+  filters: { entityTypes: ['concept'], minImportance: 5 }
+});
+```
+
+## Graph Algorithms
+
+```typescript
+// Shortest path between entities
+const path = await ctx.graphTraversal.findShortestPath('A', 'Z');
+
+// All paths up to max depth
+const paths = await ctx.graphTraversal.findAllPaths('A', 'Z', { maxDepth: 5 });
+
+// Centrality analysis
+const centrality = await ctx.graphTraversal.getCentrality({ algorithm: 'pagerank' });
+
+// Connected components
+const components = await ctx.graphTraversal.getConnectedComponents();
+```
+
+## Import/Export
+
+```typescript
+// Export to JSON
+const json = await ctx.ioManager.exportGraph('json');
+
+// Export to CSV
+const csv = await ctx.ioManager.exportGraph('csv');
+
+// Export to GraphML (with compression)
+await ctx.ioManager.exportGraph('graphml', {
+  outputPath: './graph.graphml.br',
+  compress: true
+});
+
+// Import from file
+await ctx.ioManager.importGraph('json', jsonData, { mergeStrategy: 'merge' });
+```
+
+## Hierarchical Organization
+
+```typescript
+// Set parent
+await ctx.entityManager.setEntityParent('Component', 'Module');
+
+// Get hierarchy
+const children = await ctx.entityManager.getChildren('Module');
+const ancestors = await ctx.entityManager.getAncestors('Component');
+const subtree = await ctx.entityManager.getSubtree('Module');
+```
+
+## Tag Management
+
+```typescript
+// Add/remove tags
+await ctx.entityManager.addTags('Entity1', ['tag1', 'tag2']);
+await ctx.entityManager.removeTags('Entity1', ['tag1']);
+
+// Tag aliases (synonyms)
+await ctx.tagManager.addTagAlias('js', 'javascript');
+
+// Bulk operations
+await ctx.entityManager.addTagsToMultipleEntities(['E1', 'E2'], ['shared-tag']);
+```
+
+## API Reference
+
+### EntityManager
+
+| Method | Description |
+|--------|-------------|
+| `createEntities(entities)` | Create multiple entities |
+| `deleteEntities(names)` | Delete entities by name |
+| `getEntityByName(name)` | Get single entity |
+| `addObservations(name, observations)` | Add observations to entity |
+| `deleteObservations(name, observations)` | Remove observations |
+| `addTags(name, tags)` | Add tags to entity |
+| `removeTags(name, tags)` | Remove tags from entity |
+| `setImportance(name, score)` | Set importance (0-10) |
+| `setEntityParent(name, parentName)` | Set hierarchy parent |
+| `getChildren(name)` | Get child entities |
+| `getAncestors(name)` | Get ancestor chain |
+| `getDescendants(name)` | Get all descendants |
+
+### SearchManager
+
+| Method | Description |
+|--------|-------------|
+| `search(query, options)` | Basic search |
+| `searchRanked(query, options)` | TF-IDF ranked search |
+| `booleanSearch(query, options)` | Boolean operators |
+| `fuzzySearch(query, options)` | Typo-tolerant |
+| `hybridSearch(query, options)` | Multi-signal search |
+| `smartSearch(query, options)` | AI-assisted refinement |
+
+### IOManager
+
+| Method | Description |
+|--------|-------------|
+| `exportGraph(format, options)` | Export to format |
+| `importGraph(format, data, options)` | Import from format |
+| `createBackup(options)` | Create backup |
+| `restoreBackup(path)` | Restore from backup |
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.0 (for development)
+
+## License
+
+MIT
+
+## Related
+
+- [@danielsimonjr/memory-mcp](https://github.com/danielsimonjr/memory-mcp) - MCP server built on this library

package/dist/core/EntityManager.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Entity Manager
+ *
+ * Handles CRUD operations for entities in the knowledge graph.
+ * Focused on core entity and tag operations only (Phase 4: Consolidate God Objects).
+ *
+ * @module core/EntityManager
+ */
+import type { Entity, LongRunningOperationOptions } from '../types/index.js';
+import type { GraphStorage } from './GraphStorage.js';
+/**
+ * Manages entity operations with automatic timestamp handling.
+ */
+export declare class EntityManager {
+    private storage;
+    constructor(storage: GraphStorage);
+    /**
+     * Create multiple entities in a single batch operation.
+     *
+     * This method performs the following operations:
+     * - Filters out entities that already exist (duplicate names)
+     * - Automatically adds createdAt and lastModified timestamps
+     * - Normalizes all tags to lowercase for consistent searching
+     * - Validates importance values (must be between 0-10)
+     *
+     * Phase 9B: Supports progress tracking and cancellation via LongRunningOperationOptions.
+     *
+     * @param entities - Array of entities to create. Each entity must have a unique name.
+     * @param options - Optional progress/cancellation options (Phase 9B)
+     * @returns Promise resolving to array of newly created entities (excludes duplicates)
+     * @throws {InvalidImportanceError} If any entity has importance outside the valid range [0-10]
+     * @throws {OperationCancelledError} If operation is cancelled via signal (Phase 9B)
+     *
+     * @example
+     * ```typescript
+     * const manager = new EntityManager(storage);
+     *
+     * // Create single entity
+     * const results = await manager.createEntities([{
+     *   name: 'Alice',
+     *   entityType: 'person',
+     *   observations: ['Works as engineer', 'Lives in Seattle'],
+     *   importance: 7,
+     *   tags: ['Team', 'Engineering']
+     * }]);
+     *
+     * // Create multiple entities at once
+     * const users = await manager.createEntities([
+     *   { name: 'Bob', entityType: 'person', observations: [] },
+     *   { name: 'Charlie', entityType: 'person', observations: [] }
+     * ]);
+     *
+     * // With progress tracking and cancellation (Phase 9B)
+     * const controller = new AbortController();
+     * const results = await manager.createEntities(largeEntityArray, {
+     *   signal: controller.signal,
+     *   onProgress: (p) => console.log(`${p.percentage}% complete`),
+     * });
+     * ```
+     */
+    createEntities(entities: Entity[], options?: LongRunningOperationOptions): Promise<Entity[]>;
+    /**
+     * Delete multiple entities by name in a single batch operation.
+     *
+     * This method performs cascading deletion:
+     * - Removes all specified entities from the graph
+     * - Automatically removes all relations where these entities are source or target
+     * - Silently ignores entity names that don't exist (no error thrown)
+     *
+     * @param entityNames - Array of entity names to delete
+     * @returns Promise that resolves when deletion is complete
+     *
+     * @example
+     * ```typescript
+     * const manager = new EntityManager(storage);
+     *
+     * // Delete single entity
+     * await manager.deleteEntities(['Alice']);
+     *
+     * // Delete multiple entities at once
+     * await manager.deleteEntities(['Bob', 'Charlie', 'Dave']);
+     *
+     * // Safe to delete non-existent entities (no error)
+     * await manager.deleteEntities(['NonExistent']); // No error thrown
+     * ```
+     */
+    deleteEntities(entityNames: string[]): Promise<void>;
+    /**
+     * Retrieve a single entity by its unique name.
+     *
+     * This is a read-only operation that does not modify the graph.
+     * Entity names are case-sensitive.
+     *
+     * @param name - The unique name of the entity to retrieve
+     * @returns Promise resolving to the Entity object if found, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const manager = new EntityManager(storage);
+     *
+     * // Get an existing entity
+     * const alice = await manager.getEntity('Alice');
+     * if (alice) {
+     *   console.log(alice.observations);
+     *   console.log(alice.importance);
+     * }
+     *
+     * // Handle non-existent entity
+     * const missing = await manager.getEntity('NonExistent');
+     * console.log(missing); // null
+     * ```
+     */
+    getEntity(name: string): Promise<Entity | null>;
+    /**
+     * Update one or more fields of an existing entity.
+     *
+     * This method allows partial updates - only the fields specified in the updates
+     * object will be changed. All other fields remain unchanged.
+     * The lastModified timestamp is automatically updated.
+     *
+     * @param name - The unique name of the entity to update
+     * @param updates - Partial entity object containing only the fields to update
+     * @returns Promise resolving to the fully updated Entity object
+     * @throws {EntityNotFoundError} If no entity with the given name exists
+     *
+     * @example
+     * ```typescript
+     * const manager = new EntityManager(storage);
+     *
+     * // Update importance only
+     * const updated = await manager.updateEntity('Alice', {
+     *   importance: 9
+     * });
+     *
+     * // Update multiple fields
+     * await manager.updateEntity('Bob', {
+     *   entityType: 'senior_engineer',
+     *   tags: ['leadership', 'architecture'],
+     *   observations: ['Led project X', 'Designed system Y']
+     * });
+     *
+     * // Add observations (requires reading existing entity first)
+     * const entity = await manager.getEntity('Charlie');
+     * if (entity) {
+     *   await manager.updateEntity('Charlie', {
+     *     observations: [...entity.observations, 'New observation']
+     *   });
+     * }
+     * ```
+     */
+    updateEntity(name: string, updates: Partial<Entity>): Promise<Entity>;
+    /**
+     * Update multiple entities in a single batch operation.
+     *
+     * This method is more efficient than calling updateEntity multiple times
+     * as it loads and saves the graph only once. All updates are applied atomically.
+     * The lastModified timestamp is automatically updated for all entities.
+     *
+     * @param updates - Array of updates, each containing entity name and changes
+     * @returns Promise resolving to array of updated entities
+     * @throws {EntityNotFoundError} If any entity is not found
+     * @throws {ValidationError} If any update data is invalid
+     *
+     * @example
+     * ```typescript
+     * const manager = new EntityManager(storage);
+     *
+     * // Update multiple entities at once
+     * const updated = await manager.batchUpdate([
+     *   { name: 'Alice', updates: { importance: 9 } },
+     *   { name: 'Bob', updates: { importance: 8, tags: ['senior'] } },
+     *   { name: 'Charlie', updates: { entityType: 'lead_engineer' } }
+     * ]);
+     *
+     * console.log(`Updated ${updated.length} entities`);
+     *
+     * // Efficiently update many entities (single graph load/save)
+     * const massUpdate = employees.map(name => ({
+     *   name,
+     *   updates: { tags: ['team-2024'] }
+     * }));
+     * await manager.batchUpdate(massUpdate);
+     * ```
+     */
+    batchUpdate(updates: Array<{
+        name: string;
+        updates: Partial<Entity>;
+    }>): Promise<Entity[]>;
+    /**
+     * Add tags to an entity.
+     *
+     * Tags are normalized to lowercase and duplicates are filtered out.
+     *
+     * @param entityName - Name of the entity
+     * @param tags - Tags to add
+     * @returns Result with entity name and added tags
+     * @throws {EntityNotFoundError} If entity is not found
+     */
+    addTags(entityName: string, tags: string[]): Promise<{
+        entityName: string;
+        addedTags: string[];
+    }>;
+    /**
+     * Remove tags from an entity.
+     *
+     * @param entityName - Name of the entity
+     * @param tags - Tags to remove
+     * @returns Result with entity name and removed tags
+     * @throws {EntityNotFoundError} If entity is not found
+     */
+    removeTags(entityName: string, tags: string[]): Promise<{
+        entityName: string;
+        removedTags: string[];
+    }>;
+    /**
+     * Set importance level for an entity.
+     *
+     * @param entityName - Name of the entity
+     * @param importance - Importance level (0-10)
+     * @returns Result with entity name and importance
+     * @throws {EntityNotFoundError} If entity is not found
+     * @throws {Error} If importance is out of range
+     */
+    setImportance(entityName: string, importance: number): Promise<{
+        entityName: string;
+        importance: number;
+    }>;
+    /**
+     * Add tags to multiple entities in a single operation.
+     *
+     * OPTIMIZED: Uses Map for O(1) entity lookups instead of O(n) find() per entity.
+     *
+     * @param entityNames - Names of entities to tag
+     * @param tags - Tags to add to each entity
+     * @returns Array of results showing which tags were added to each entity
+     */
+    addTagsToMultipleEntities(entityNames: string[], tags: string[]): Promise<{
+        entityName: string;
+        addedTags: string[];
+    }[]>;
+    /**
+     * Replace a tag with a new tag across all entities (rename tag).
+     *
+     * @param oldTag - Tag to replace
+     * @param newTag - New tag value
+     * @returns Result with affected entities and count
+     */
+    replaceTag(oldTag: string, newTag: string): Promise<{
+        affectedEntities: string[];
+        count: number;
+    }>;
+    /**
+     * Merge two tags into one target tag across all entities.
+     *
+     * Combines tag1 and tag2 into targetTag. Any entity with either tag1 or tag2
+     * will have both removed and targetTag added (if not already present).
+     *
+     * @param tag1 - First tag to merge
+     * @param tag2 - Second tag to merge
+     * @param targetTag - Target tag to merge into
+     * @returns Object with affected entity names and count
+     */
+    mergeTags(tag1: string, tag2: string, targetTag: string): Promise<{
+        affectedEntities: string[];
+        count: number;
+    }>;
+}
+//# sourceMappingURL=EntityManager.d.ts.map

package/dist/core/EntityManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityManager.d.ts","sourceRoot":"","sources":["../../src/core/EntityManager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAyBtD;;GAEG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,YAAY;IAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,MAAM,EAAE,CAAC;IA+EpB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB1D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAKrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAuB3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,WAAW,CACf,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC,GACzD,OAAO,CAAC,MAAM,EAAE,CAAC;IAuCpB;;;;;;;;;OASG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAsBvG;;;;;;;OAOG;IACG,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAgC5G;;;;;;;;OAQG;IACG,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAkBhH;;;;;;;;OAQG;IACG,yBAAyB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAuC9H;;;;;;OAMG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAuBxG;;;;;;;;;;OAUG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAmCvH"}