{"_id":"@basekick-labs/memtrace-sdk","_rev":"3-2b8cd0b2838b9d6f8c26e954d5219996","name":"@basekick-labs/memtrace-sdk","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@basekick-labs/memtrace-sdk","version":"0.1.0","keywords":["memtrace","ai","agents","memory","llm"],"author":{"name":"Basekick Labs"},"license":"MIT","_id":"@basekick-labs/memtrace-sdk@0.1.0","maintainers":[{"name":"ignaciovdk","email":"support@basekick.net"}],"homepage":"https://memtrace.ai","bugs":{"url":"https://github.com/Basekick-Labs/memtrace/issues"},"dist":{"shasum":"12a6430746a51a5342a915bb7db669539bcdb1f0","tarball":"https://registry.npmjs.org/@basekick-labs/memtrace-sdk/-/memtrace-sdk-0.1.0.tgz","fileCount":10,"integrity":"sha512-oPUAzlybMmNxfoeigOnqgLKmbuVGDXKd6QA3jHm2U79mRkJLkVIhvp57tV1Hs0GTOL22vY82GZdMd+09kKZWGQ==","signatures":[{"sig":"MEUCIEINbSpqu0d2/ImFKLuKyCZIiaO/fdUXhwGWFARjla/bAiEA6cen3DJgIudG1RtWUf6Cqk8bHUKITT9MNvvtYaartVw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":60428},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"9c9b5d2c1f776513289b74b91e7093f8871d8c6a","scripts":{"lint":"tsc --noEmit","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"ignaciovdk","email":"support@basekick.net"},"repository":{"url":"git+https://github.com/Basekick-Labs/memtrace.git","type":"git","directory":"sdks/typescript"},"_npmVersion":"11.12.1","description":"TypeScript SDK for Memtrace — LLM-agnostic memory layer for AI agents","directories":{},"_nodeVersion":"22.22.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^2.0.0","typescript":"^5.3.0","@types/node":"^25.2.2"},"_npmOperationalInternal":{"tmp":"tmp/memtrace-sdk_0.1.0_1776360424941_0.7764121022942039","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@basekick-labs/memtrace-sdk","version":"0.1.1","keywords":["memtrace","ai","agents","memory","llm"],"author":{"name":"Basekick Labs"},"license":"MIT","_id":"@basekick-labs/memtrace-sdk@0.1.1","maintainers":[{"name":"ignaciovdk","email":"support@basekick.net"}],"homepage":"https://basekick.net/memtrace","bugs":{"url":"https://github.com/Basekick-Labs/memtrace/issues"},"dist":{"shasum":"9704f358592c1829326782161db34243b7870655","tarball":"https://registry.npmjs.org/@basekick-labs/memtrace-sdk/-/memtrace-sdk-0.1.1.tgz","fileCount":10,"integrity":"sha512-n4xmWIwSj6A6PRgqhvJYVKUzLWpOahrYK83bvqwKtSXMceCng2P0vcFPxTHmD0ApL3mren/T97iluK+haoS+IA==","signatures":[{"sig":"MEQCIEANYhMZ0QaUO2sdu2L1x8dBfX+545s4buFywKuabIWmAiA/IH6GqbaP8YkzbEmqX6b+3rTgrQjXNWlmtZtABiVNGw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":60591},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"21b001dc34b70d6045b9b91571136f7ee8c133ec","scripts":{"lint":"tsc --noEmit","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"ignaciovdk","email":"support@basekick.net"},"repository":{"url":"git+https://github.com/Basekick-Labs/memtrace.git","type":"git","directory":"sdks/typescript"},"_npmVersion":"11.12.1","description":"TypeScript SDK for Memtrace — LLM-agnostic memory layer for AI agents","directories":{},"_nodeVersion":"22.22.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^2.0.0","typescript":"^5.3.0","@types/node":"^25.2.2"},"_npmOperationalInternal":{"tmp":"tmp/memtrace-sdk_0.1.1_1776360834163_0.7826431475883759","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@basekick-labs/memtrace-sdk","version":"0.2.0","description":"TypeScript SDK for Memtrace — LLM-agnostic memory layer for AI agents","license":"MIT","author":{"name":"Basekick Labs"},"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"engines":{"node":">=18"},"scripts":{"build":"tsup","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","lint":"tsc --noEmit"},"devDependencies":{"@types/node":"^25.2.2","tsup":"^8.0.0","typescript":"^5.3.0","vitest":"^2.0.0"},"repository":{"type":"git","url":"git+https://github.com/Basekick-Labs/memtrace.git","directory":"sdks/typescript"},"homepage":"https://basekick.net/memtrace","bugs":{"url":"https://github.com/Basekick-Labs/memtrace/issues"},"publishConfig":{"access":"public"},"keywords":["memtrace","ai","agents","memory","llm"],"gitHead":"30026656db62e197e7a08c0cdaeaa91921d5c7ef","_id":"@basekick-labs/memtrace-sdk@0.2.0","_nodeVersion":"22.22.1","_npmVersion":"11.12.1","dist":{"integrity":"sha512-/O+iyD8O/5zjchstzYroyaaTF3UrkUZS1UmoG7WJgmj8PYTHvS8OEgVHeGoWvKDotrIjQNEaxhAhC+7U8TZK7Q==","shasum":"fea01bb5b567cd468e3443ffadb2a89296556a04","tarball":"https://registry.npmjs.org/@basekick-labs/memtrace-sdk/-/memtrace-sdk-0.2.0.tgz","fileCount":10,"unpackedSize":65988,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHKa7lSypI/aCgg2L/hPiH3rWtYaruKz7GfeM+epDPyYAiArM8qfuh19sAZv75c7utbp07GEiQFsI9pBwdZsyrVnnw=="}]},"_npmUser":{"name":"ignaciovdk","email":"support@basekick.net"},"directories":{},"maintainers":[{"name":"ignaciovdk","email":"support@basekick.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/memtrace-sdk_0.2.0_1777306055348_0.1051867078098434"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-16T17:27:04.867Z","modified":"2026-04-27T16:07:35.629Z","0.1.0":"2026-04-16T17:27:05.123Z","0.1.1":"2026-04-16T17:33:54.301Z","0.2.0":"2026-04-27T16:07:35.493Z"},"bugs":{"url":"https://github.com/Basekick-Labs/memtrace/issues"},"author":{"name":"Basekick Labs"},"license":"MIT","homepage":"https://basekick.net/memtrace","keywords":["memtrace","ai","agents","memory","llm"],"repository":{"type":"git","url":"git+https://github.com/Basekick-Labs/memtrace.git","directory":"sdks/typescript"},"description":"TypeScript SDK for Memtrace — LLM-agnostic memory layer for AI agents","maintainers":[{"name":"ignaciovdk","email":"support@basekick.net"}],"readme":"# Memtrace TypeScript SDK\n\nTypeScript/Node.js client for [Memtrace](https://basekick.net/memtrace) — LLM-agnostic memory layer for AI agents.\n\n## Installation\n\n```bash\nnpm install @basekick-labs/memtrace-sdk\n```\n\n## Quick Start\n\n```typescript\nimport { Memtrace } from '@basekick-labs/memtrace-sdk'\n\nconst client = new Memtrace('http://localhost:9100', 'mtk_your_api_key')\n\n// Store a memory\nawait client.remember('agent_1', 'User prefers dark mode')\n\n// Recall recent memories\nconst memories = await client.recall('agent_1', '24h')\nfor (const m of memories.memories) {\n  console.log(`[${m.time}] ${m.content}`)\n}\n\n// Log a decision\nawait client.decide('agent_1', 'Use PostgreSQL', 'Better JSON support for metadata')\n```\n\n## Full API\n\n### Memory Operations\n\n```typescript\nimport { Memtrace } from '@basekick-labs/memtrace-sdk'\n\nconst client = new Memtrace('http://localhost:9100', 'mtk_...')\n\n// Add a single memory with full control\nconst mem = await client.addMemory({\n  agent_id: 'agent_1',\n  session_id: 'sess_1',\n  memory_type: 'episodic',\n  event_type: 'observation',\n  content: 'User clicked the settings button',\n  tags: ['ui', 'navigation'],\n  importance: 0.7,\n})\n\n// Add multiple memories in a batch\nconst memories = await client.addMemories([\n  { agent_id: 'agent_1', memory_type: 'episodic', event_type: 'general', content: 'First' },\n  { agent_id: 'agent_1', memory_type: 'episodic', event_type: 'general', content: 'Second' },\n])\n\n// List with filters\nconst result = await client.listMemories({\n  agent_id: 'agent_1',\n  memory_type: 'decision',\n  since: '7d',\n  limit: 50,\n  order: 'desc',\n})\n\n// Search with structured query\nconst searchResult = await client.searchMemories({\n  agent_id: 'agent_1',\n  memory_types: ['episodic', 'decision'],\n  content_contains: 'dark mode',\n  min_importance: 0.5,\n})\n```\n\n### Agent Management\n\n```typescript\nimport { Memtrace } from '@basekick-labs/memtrace-sdk'\n\nconst client = new Memtrace('http://localhost:9100', 'mtk_...')\n\n// Register an agent\nconst agent = await client.registerAgent({\n  name: 'my-agent',\n  description: 'Handles customer support',\n  config: { model: 'gpt-4' },\n})\n\n// Get agent details\nconst fetched = await client.getAgent('agent_1')\n\n// Get agent memory stats\nconst stats = await client.getAgentStats('agent_1')\nconsole.log(`Total memories: ${stats.memory_count}`)\nconsole.log(`Active sessions: ${stats.active_sessions}`)\n```\n\n### Session Management\n\n```typescript\nimport { Memtrace } from '@basekick-labs/memtrace-sdk'\n\nconst client = new Memtrace('http://localhost:9100', 'mtk_...')\n\n// Create a session\nconst session = await client.createSession({\n  agent_id: 'agent_1',\n  metadata: { task: 'onboarding' },\n})\n\n// Get LLM-formatted context\nconst ctx = await client.getSessionContext(session.id, {\n  since: '2h',\n  include_types: ['episodic', 'decision'],\n  max_tokens: 4000,\n})\nconsole.log(ctx.context) // Markdown-formatted for LLM consumption\n\n// List sessions (optionally filtered by agent)\nconst all = await client.listSessions()\nconst forAgent = await client.listSessions('agent_1')\n\n// Close the session\nawait client.closeSession(session.id)\n```\n\n## Multi-tenant Deployments\n\nA Memtrace deployment can serve multiple organizations, each routed to its own Arc instance. The SDK is unchanged — you still pass `(baseURL, apiKey)`. Memtrace looks up the organization that owns your API key and forwards reads and writes to that org's Arc instance automatically.\n\nTo work against a different org, ask an administrator to run `memtrace org create` and `memtrace key create --org <org_id>`, then use that key with the same SDK call.\n\nIf a key is bound to an org that has no Arc instance configured yet, requests reject with `NoArcInstanceError` (see Error Handling below).\n\n## Error Handling\n\n```typescript\nimport {\n  Memtrace,\n  MemtraceError,\n  AuthenticationError,\n  NotFoundError,\n  ConflictError,\n  NoArcInstanceError,\n} from '@basekick-labs/memtrace-sdk'\n\nconst client = new Memtrace('http://localhost:9100', 'mtk_...')\n\ntry {\n  const agent = await client.getAgent('nonexistent')\n} catch (e) {\n  if (e instanceof NotFoundError) {\n    console.log('Agent not found')\n  } else if (e instanceof AuthenticationError) {\n    console.log('Invalid API key')\n  } else if (e instanceof ConflictError) {\n    console.log('Duplicate resource')\n  } else if (e instanceof NoArcInstanceError) {\n    // Caller's org has no Arc instance configured. An admin must run\n    // `memtrace org add-arc <org_id>`. Until then every read/write is 503.\n    console.log('Memtrace is not provisioned for this org yet')\n  } else if (e instanceof MemtraceError) {\n    console.log(`API error (${e.statusCode}): ${e.message}`)\n  }\n}\n```\n\n## Configuration\n\n```typescript\nconst client = new Memtrace('http://localhost:9100', 'mtk_...', {\n  timeout: 10_000, // Request timeout in ms (default: 30000)\n})\n```\n\n## Requirements\n\n- Node.js >= 18 (uses native `fetch`)\n- Zero runtime dependencies\n\n## Development\n\n```bash\ncd sdks/typescript\nnpm install\nnpm run build\nnpm test\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}