{"_id":"@aintandem/context-manager-client","_rev":"5-eea2dfc7a9b4649f0651394242c3f31e","name":"@aintandem/context-manager-client","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aintandem/context-manager-client","version":"0.1.0","keywords":["kai","context-manager","memory","ai","mem0","hierarchical","typescript","client"],"author":{"name":"Lex Yang"},"license":"MIT","_id":"@aintandem/context-manager-client@0.1.0","maintainers":[{"name":"misterlex223","email":"misterlex223@gmail.com"}],"homepage":"https://github.com/cotandem/context-manager#readme","bugs":{"url":"https://github.com/cotandem/context-manager/issues"},"dist":{"shasum":"2122319de0e199eef39465b318fad6c158626805","tarball":"https://registry.npmjs.org/@aintandem/context-manager-client/-/context-manager-client-0.1.0.tgz","fileCount":63,"integrity":"sha512-mdFYDe8Dvfka55fMrDpuDENjnALUtn9E6S/hvn53Ww6yT08VV3RQE4RC8g/DzWOF2f5Rz5XVmtp7vDILlVVqFg==","signatures":[{"sig":"MEYCIQCuGUbhT9LnXOWOhsxxpa3EeoHzsg7nnhRGJa9YaKJ8wAIhAKZcbSnXPX4dIOX4jlujj+8LNAKbxn4gOSQLSNdhJuy6","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":101483},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","engines":{"node":">=16.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"1d9953f9dd2ef390b67fd9a31ecf1f0e34c77e25","scripts":{"lint":"eslint 'src/**/*.ts'","test":"jest","build":"npm run build:cjs && npm run build:esm && npm run build:types","format":"prettier --write 'src/**/*.ts'","build:cjs":"tsc --module commonjs --outDir dist --declaration false","build:esm":"tsc --module esnext --outDir dist-esm && mv dist-esm/index.js dist/index.mjs && rm -rf dist-esm","test:watch":"jest --watch","build:types":"tsc --declaration --emitDeclarationOnly --outDir dist","test:coverage":"jest --coverage","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"misterlex223","email":"misterlex223@gmail.com"},"repository":{"url":"git+https://github.com/cotandem/context-manager.git","type":"git","directory":"clients/typescript"},"_npmVersion":"10.9.3","description":"TypeScript client library for Kai Context Manager - hierarchical memory management for AI applications","directories":{},"_nodeVersion":"22.19.0","dependencies":{"axios":"^1.6.0","axios-retry":"^4.0.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","eslint":"^8.50.0","ts-jest":"^29.1.0","prettier":"^3.0.0","typescript":"^5.3.0","@types/jest":"^29.5.0","@types/node":"^20.0.0","@typescript-eslint/parser":"^6.0.0","@typescript-eslint/eslint-plugin":"^6.0.0"},"_npmOperationalInternal":{"tmp":"tmp/context-manager-client_0.1.0_1763479941044_0.4939822873829789","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-11-18T15:32:20.977Z","modified":"2026-01-17T16:42:33.100Z","0.1.0":"2025-11-18T15:32:21.231Z"},"bugs":{"url":"https://github.com/cotandem/context-manager/issues"},"author":{"name":"Lex Yang"},"license":"MIT","homepage":"https://github.com/cotandem/context-manager#readme","keywords":["kai","context-manager","memory","ai","mem0","hierarchical","typescript","client"],"repository":{"url":"git+https://github.com/cotandem/context-manager.git","type":"git","directory":"clients/typescript"},"description":"TypeScript client library for Kai Context Manager - hierarchical memory management for AI applications","maintainers":[{"email":"misterlex223@gmail.com","name":"misterlex223"}],"readme":"# Kai Context Manager - TypeScript Client\n\nA TypeScript client library for the [Kai Context Manager](../../README.md), providing hierarchical memory management for AI applications built on top of Mem0.\n\n## Features\n\n- **Full TypeScript Support** - Complete type definitions for all API operations\n- **Hierarchical Organization** - Manage organizations, workspaces, projects, and tasks\n- **Memory Management** - CRUD operations and semantic search for memories\n- **Document Import** - Import and chunk documents automatically\n- **File Synchronization** - Track and sync file changes\n- **Advanced Features**:\n  - Automatic retry with exponential backoff\n  - Response caching with TTL\n  - Batch operations with concurrency control\n  - Structured logging with configurable levels\n  - Custom error classes for better error handling\n\n## Installation\n\n```bash\nnpm install @kai/context-manager-client\n```\n\nOr with yarn:\n\n```bash\nyarn add @kai/context-manager-client\n```\n\n## Quick Start\n\n```typescript\nimport { KaiContextClient, LogLevel } from '@kai/context-manager-client';\n\n// Initialize client\nconst client = new KaiContextClient({\n  baseUrl: 'http://localhost:8001',\n  logging: { level: LogLevel.INFO }\n});\n\n// Create hierarchy\nconst org = await client.hierarchy.createOrganization({\n  name: 'MyCompany',\n  folder_path: '/orgs/mycompany'\n});\n\nconst workspace = await client.hierarchy.createWorkspace({\n  organization_id: org.id,\n  name: 'Engineering'\n});\n\nconst project = await client.hierarchy.createProject({\n  workspace_id: workspace.id,\n  name: 'API Server'\n});\n\n// Add memory\nconst memory = await client.memory.add({\n  content: 'The API uses REST architecture with JSON responses',\n  scope: 'project',\n  scope_id: project.id,\n  memory_type: 'knowledge',\n  tags: ['api', 'architecture']\n});\n\n// Search memories\nconst results = await client.memory.search({\n  query: 'What architecture does the API use?',\n  scope: 'project',\n  scope_id: project.id,\n  limit: 10\n});\n\nconsole.log(results.results[0].memory);\n```\n\n## Configuration\n\n```typescript\nimport { KaiContextClient, LogLevel } from '@kai/context-manager-client';\n\nconst client = new KaiContextClient({\n  // API endpoint\n  baseUrl: 'http://localhost:8001',\n\n  // Request timeout (ms)\n  timeout: 30000,\n\n  // Logging configuration\n  logging: {\n    level: LogLevel.DEBUG, // DEBUG, INFO, WARN, ERROR, NONE\n    prefix: '[KaiContext]'\n  },\n\n  // Retry configuration\n  retry: {\n    maxRetries: 3,\n    initialDelay: 1000,\n    maxDelay: 30000,\n    backoffFactor: 2\n  },\n\n  // Cache configuration\n  cache: {\n    enabled: true,\n    ttl: 60000, // Cache TTL in ms\n    maxSize: 100 // Max cache entries\n  },\n\n  // Custom headers\n  headers: {\n    'X-Custom-Header': 'value'\n  }\n});\n```\n\n## API Reference\n\n### Hierarchy Management\n\n```typescript\n// Organizations\nconst org = await client.hierarchy.createOrganization({\n  name: 'MyCompany',\n  folder_path: '/path/to/org'\n});\n\nconst orgData = await client.hierarchy.getOrganization(org.id);\n\n// Workspaces\nconst workspace = await client.hierarchy.createWorkspace({\n  organization_id: org.id,\n  name: 'Engineering',\n  folder_path: '/path/to/workspace'\n});\n\nconst workspaces = await client.hierarchy.listWorkspaces(org.id);\n\n// Projects\nconst project = await client.hierarchy.createProject({\n  workspace_id: workspace.id,\n  name: 'API Server',\n  folder_path: '/path/to/project'\n});\n\nconst projects = await client.hierarchy.listProjects(workspace.id);\n\n// Tasks\nconst task = await client.hierarchy.createTask({\n  project_id: project.id,\n  name: 'Implement authentication',\n  description: 'Add JWT authentication',\n  status: 'pending'\n});\n\nconst taskData = await client.hierarchy.getTask(task.id);\n\n// Get full context\nconst context = await client.hierarchy.getContext('project', project.id);\n```\n\n### Memory Operations\n\n```typescript\n// Add memory\nconst memory = await client.memory.add({\n  content: 'Important information',\n  scope: 'project',\n  scope_id: project.id,\n  memory_type: 'knowledge',\n  visibility: 'workspace',\n  tags: ['important', 'architecture'],\n  source: {\n    type: 'file',\n    file_path: '/docs/architecture.md',\n    line_start: 10,\n    line_end: 20\n  }\n});\n\n// Search memories\nconst results = await client.memory.search({\n  query: 'authentication implementation',\n  scope: 'project',\n  scope_id: project.id,\n  limit: 10,\n  include_inherited: true\n});\n\n// List memories\nconst memories = await client.memory.list({\n  scope: 'project',\n  scope_id: project.id,\n  memory_type: 'knowledge',\n  tags: ['architecture'],\n  limit: 50\n});\n\n// Get specific memory\nconst memoryData = await client.memory.get(memory.id);\n\n// Update memory\nawait client.memory.update(memory.id, {\n  content: 'Updated information'\n});\n\n// Delete memory\nawait client.memory.delete(memory.id);\n```\n\n### Document Import\n\n```typescript\n// Import single document\nconst importResult = await client.import.document({\n  file_path: '/docs/architecture.md',\n  scope: 'project',\n  scope_id: project.id,\n  memory_type: 'documentation',\n  visibility: 'workspace',\n  tags: ['docs'],\n  chunk_content: true\n});\n\n// Import folder of documents\nconst folderResult = await client.import.documentFolder({\n  folder_path: '/docs',\n  scope: 'project',\n  scope_id: project.id,\n  recursive: true,\n  file_extensions: ['.md', '.txt'],\n  tags: ['documentation']\n});\n\n// Import spec file (YAML/JSON)\nconst specResult = await client.import.spec({\n  file_path: '/config/api-spec.yaml',\n  scope: 'project',\n  scope_id: project.id,\n  memory_type: 'specification'\n});\n\n// Import spec folder\nconst specFolderResult = await client.import.specFolder({\n  folder_path: '/specs',\n  scope: 'project',\n  scope_id: project.id,\n  recursive: true\n});\n```\n\n### File Synchronization\n\n```typescript\n// Sync single file\nconst syncResult = await client.sync.file({\n  file_path: '/docs/architecture.md',\n  scope: 'project',\n  scope_id: project.id,\n  tags: ['docs']\n});\n\n// Sync folder\nconst syncFolderResult = await client.sync.folder({\n  folder_path: '/docs',\n  scope: 'project',\n  scope_id: project.id,\n  recursive: true,\n  file_extensions: ['.md', '.txt']\n});\n\n// Check sync status (dry run)\nconst checkResult = await client.sync.check({\n  folder_path: '/docs',\n  scope: 'project',\n  scope_id: project.id,\n  recursive: true\n});\n\n// Cleanup deleted files\nconst cleanupResult = await client.sync.cleanup({\n  scope: 'project',\n  scope_id: project.id,\n  folder_path: '/docs'\n});\n\n// Get sync statistics\nconst stats = await client.sync.stats();\n\n// List tracked files\nconst files = await client.sync.files();\n```\n\n## Helper Functions\n\n### Create Full Hierarchy\n\n```typescript\nimport { createFullHierarchy } from '@kai/context-manager-client';\n\nconst hierarchy = await createFullHierarchy(client, {\n  organization: {\n    name: 'MyCompany',\n    folder_path: '/orgs/mycompany'\n  },\n  workspace: {\n    name: 'Engineering'\n  },\n  project: {\n    name: 'API Server'\n  },\n  task: {\n    name: 'Add authentication',\n    description: 'Implement JWT auth'\n  }\n});\n\n// Access created entities\nconsole.log(hierarchy.organization.id);\nconsole.log(hierarchy.workspace.id);\nconsole.log(hierarchy.project.id);\nconsole.log(hierarchy.task?.id);\n```\n\n### Batch Import Files\n\n```typescript\nimport { batchImportFiles } from '@kai/context-manager-client';\n\nconst result = await batchImportFiles(\n  client,\n  {\n    files: [\n      '/docs/file1.md',\n      '/docs/file2.md',\n      '/docs/file3.md'\n    ],\n    scope: 'project',\n    scope_id: project.id,\n    tags: ['documentation']\n  },\n  (completed, total) => {\n    console.log(`Progress: ${completed}/${total}`);\n  }\n);\n\nconsole.log(`Imported ${result.successful} files, ${result.failed} failed`);\n```\n\n### Batch Sync Files\n\n```typescript\nimport { batchSyncFiles } from '@kai/context-manager-client';\n\nconst result = await batchSyncFiles(\n  client,\n  {\n    files: ['/docs/file1.md', '/docs/file2.md'],\n    scope: 'project',\n    scope_id: project.id\n  },\n  (completed, total) => {\n    console.log(`Syncing: ${completed}/${total}`);\n  }\n);\n\nconsole.log(`Total changes: ${result.total_changes.memories_updated} updated`);\n```\n\n### Import with Auto Hierarchy\n\n```typescript\nimport { importWithAutoHierarchy } from '@kai/context-manager-client';\n\nconst result = await importWithAutoHierarchy(\n  client,\n  ['/docs/file1.md', '/docs/file2.md'],\n  {\n    organization: { name: 'MyCompany' },\n    workspace: { name: 'Engineering' },\n    project: { name: 'API Server' }\n  },\n  (completed, total) => {\n    console.log(`Progress: ${completed}/${total}`);\n  }\n);\n\nconsole.log('Hierarchy:', result.hierarchy);\nconsole.log('Import:', result.import);\n```\n\n## Error Handling\n\n```typescript\nimport {\n  KaiApiError,\n  NetworkError,\n  ValidationError,\n  TimeoutError\n} from '@kai/context-manager-client';\n\ntry {\n  await client.memory.add({ /* ... */ });\n} catch (error) {\n  if (error instanceof KaiApiError) {\n    console.error('API Error:', error.statusCode, error.message);\n    console.error('Response:', error.response);\n  } else if (error instanceof NetworkError) {\n    console.error('Network Error:', error.message);\n  } else if (error instanceof TimeoutError) {\n    console.error('Request timed out');\n  } else if (error instanceof ValidationError) {\n    console.error('Validation Error:', error.field, error.message);\n  }\n}\n```\n\n## Advanced Usage\n\n### Custom Batch Processing\n\n```typescript\nimport { BatchProcessor } from '@kai/context-manager-client';\n\nconst batchProcessor = new BatchProcessor({\n  concurrency: 5,\n  stopOnError: false\n});\n\nconst results = await batchProcessor.process(\n  items,\n  async (item) => {\n    // Process item\n    return await processItem(item);\n  },\n  (completed, total) => {\n    console.log(`Progress: ${completed}/${total}`);\n  }\n);\n```\n\n### Cache Management\n\n```typescript\n// Clear all cache\nclient.clearCache();\n\n// Invalidate specific pattern\nclient.memory['invalidateCache']('/api/memories');\n\n// Change log level at runtime\nimport { LogLevel } from '@kai/context-manager-client';\nclient.setLogLevel(LogLevel.DEBUG);\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Test\nnpm test\n\n# Watch mode\nnpm run test:watch\n\n# Coverage\nnpm run test:coverage\n\n# Lint\nnpm run lint\n\n# Format\nnpm run format\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please see the main repository for contribution guidelines.\n\n## Support\n\nFor issues and questions, please visit the [GitHub repository](https://github.com/cotandem/context-manager).\n","readmeFilename":"README.md"}