@danielsimonjr/memoryjs 1.2.0 → 1.2.1

package/README.md

@@ -1,13 +1,13 @@
 # MemoryJS
 
-[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/danielsimonjr/memoryjs)
+[![Version](https://img.shields.io/badge/version-1.2.0-blue.svg)](https://github.com/danielsimonjr/memoryjs)
 [![NPM](https://img.shields.io/npm/v/@danielsimonjr/memoryjs.svg)](https://www.npmjs.com/package/@danielsimonjr/memoryjs)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 
 A **TypeScript knowledge graph library** for managing entities, relations, and observations with **advanced search capabilities**, **hierarchical organization**, and **multiple storage backends**.
 
-> **Core library** powering [@danielsimonjr/memory-mcp](https://www.npmjs.com/package/@danielsimonjr/memory-mcp). Provides 73 TypeScript files, ~29K lines of code, dual storage backends (JSONL/SQLite), and sophisticated search algorithms including BM25, TF-IDF, fuzzy, semantic, and hybrid search.
+> **Core library** powering [@danielsimonjr/memory-mcp](https://www.npmjs.com/package/@danielsimonjr/memory-mcp). Provides **93 TypeScript files**, **~41K lines of code**, dual storage backends (JSONL/SQLite), sophisticated search algorithms (BM25, TF-IDF, fuzzy, semantic, hybrid), and a complete **Agent Memory System** for AI agents.
 
 ## Table of Contents
 
@@ -18,6 +18,7 @@ A **TypeScript knowledge graph library** for managing entities, relations, and o
 - [Storage Options](#storage-options)
 - [Search Capabilities](#search-capabilities)
 - [Graph Algorithms](#graph-algorithms)
+- [Agent Memory System](#agent-memory-system)
 - [API Reference](#api-reference)
 - [Configuration](#configuration)
 - [Development](#development)
@@ -50,14 +51,15 @@ A **TypeScript knowledge graph library** for managing entities, relations, and o
 
 | Module | Files | Key Components |
 |--------|-------|----------------|
+| `agent/` | 19 | AgentMemoryManager, SessionManager, DecayEngine, WorkingMemoryManager |
 | `core/` | 12 | EntityManager, GraphStorage, SQLiteStorage, TransactionManager |
 | `search/` | 29 | SearchManager, BM25Search, HybridScorer, VectorStore, QueryPlanner |
 | `features/` | 9 | IOManager, ArchiveManager, CompressionManager, StreamingExporter |
 | `utils/` | 18 | BatchProcessor, CompressedCache, WorkerPoolManager, MemoryMonitor |
-| `types/` | 2 | Entity, Relation, KnowledgeGraph interfaces |
+| `types/` | 3 | Entity, Relation, AgentEntity, SessionEntity interfaces |
 | `workers/` | 2 | Levenshtein distance calculations |
 
-**Total:** 73 TypeScript files | ~29,000 lines of code | 558 exports
+**Total:** 93 TypeScript files | ~41,000 lines of code | 657 exports | 91 classes | 216 interfaces
 
 ## Installation
 
@@ -353,6 +355,110 @@ await ctx.graphTraversal.dfs('startNode', (node) => {
 });
 ```
 
+## Agent Memory System
+
+A complete memory system for AI agents with working memory, episodic memory, decay mechanisms, and multi-agent support.
+
+### Key Components
+
+| Component | Description |
+|-----------|-------------|
+| **AgentMemoryManager** | Unified facade for all agent memory operations |
+| **SessionManager** | Session lifecycle management |
+| **WorkingMemoryManager** | Short-term memory with promotion to long-term |
+| **EpisodicMemoryManager** | Timeline-based episodic memory |
+| **DecayEngine** | Time-based memory importance decay |
+| **SalienceEngine** | Context-aware memory scoring |
+| **MultiAgentMemoryManager** | Shared memory with visibility controls |
+| **ConflictResolver** | Resolution strategies for concurrent updates |
+
+### Quick Start
+
+```typescript
+import { ManagerContext } from '@danielsimonjr/memoryjs';
+
+const ctx = new ManagerContext('./memory.jsonl');
+const agent = ctx.agentMemory();
+
+// Start a session
+const session = await agent.startSession({ agentId: 'my-agent' });
+
+// Add working memory
+await agent.addWorkingMemory({
+  sessionId: session.name,
+  content: 'User prefers dark mode',
+  importance: 7
+});
+
+// Create episodic memory
+await agent.createEpisode('Completed onboarding flow', {
+  sessionId: session.name,
+  importance: 8
+});
+
+// Retrieve context for LLM prompt
+const context = await agent.retrieveForContext({
+  maxTokens: 2000,
+  includeEpisodic: true
+});
+
+// End session
+await agent.endSession(session.name);
+```
+
+### Memory Types
+
+```typescript
+type MemoryType = 'working' | 'episodic' | 'semantic' | 'procedural';
+```
+
+- **Working Memory**: Short-term, session-scoped memories that may be promoted
+- **Episodic Memory**: Timeline-based event memories with temporal ordering
+- **Semantic Memory**: Long-term factual knowledge
+- **Procedural Memory**: Learned behaviors and patterns
+
+### Decay System
+
+Memories naturally decay over time unless reinforced:
+
+```typescript
+// Configure decay behavior
+const agent = ctx.agentMemory({
+  decay: {
+    halfLifeHours: 168,  // 1 week half-life
+    minImportance: 0.1   // Never fully forget
+  },
+  enableAutoDecay: true
+});
+
+// Reinforce important memories
+await agent.confirmMemory('memory_name', 0.1);  // Boost confidence
+await agent.promoteMemory('memory_name', 'episodic');  // Promote to long-term
+```
+
+### Multi-Agent Support
+
+```typescript
+// Register agents
+agent.registerAgent('agent_1', {
+  name: 'Research Agent',
+  type: 'llm',
+  trustLevel: 0.8,
+  capabilities: ['read', 'write']
+});
+
+// Create memories with visibility controls
+await agent.addWorkingMemory({
+  sessionId: session.name,
+  content: 'Shared insight',
+  visibility: 'shared',  // 'private' | 'shared' | 'public'
+  ownerAgentId: 'agent_1'
+});
+
+// Cross-agent search
+const results = await agent.searchCrossAgent('agent_2', 'query');
+```
+
 ## API Reference
 
 ### EntityManager
@@ -472,8 +578,18 @@ npm run typecheck     # Type checking without emit
 
 ```
 memoryjs/
-├── src/                            # Source (73 TypeScript files)
+├── src/                            # Source (93 TypeScript files)
 │   ├── index.ts                    # Entry point
+│   ├── agent/                      # Agent Memory System (19 files)
+│   │   ├── AgentMemoryManager.ts       # Unified facade
+│   │   ├── SessionManager.ts           # Session lifecycle
+│   │   ├── WorkingMemoryManager.ts     # Working memory
+│   │   ├── EpisodicMemoryManager.ts    # Episodic memory
+│   │   ├── DecayEngine.ts              # Memory decay
+│   │   ├── SalienceEngine.ts           # Context scoring
+│   │   ├── MultiAgentMemoryManager.ts  # Multi-agent support
+│   │   ├── ConflictResolver.ts         # Conflict resolution
+│   │   └── ...
 │   ├── core/                       # Core managers (12 files)
 │   │   ├── ManagerContext.ts           # Context holder (lazy init)
 │   │   ├── EntityManager.ts            # Entity CRUD + hierarchy
@@ -497,10 +613,10 @@ memoryjs/
 │   │   ├── ArchiveManager.ts           # Entity archival
 │   │   ├── CompressionManager.ts       # Duplicate detection
 │   │   └── ...
-│   ├── types/                      # TypeScript definitions (2 files)
+│   ├── types/                      # TypeScript definitions (3 files)
 │   ├── utils/                      # Shared utilities (18 files)
 │   └── workers/                    # Worker pool (2 files)
-├── tests/                          # Test suite
+├── tests/                          # Test suite (3600+ tests)
 │   ├── unit/                       # Unit tests
 │   ├── integration/                # Integration tests
 │   └── performance/                # Benchmarks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danielsimonjr/memoryjs",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Core knowledge graph library with search, storage, and graph algorithms",
   "type": "module",
   "main": "dist/index.cjs",

package/README.md.backup-1768084780988

@@ -1,266 +0,0 @@
-# @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