{"_id":"@abagraph/client","name":"@abagraph/client","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@abagraph/client","version":"0.1.0","description":"Official TypeScript client for abagraph — the bitemporal graph + vector memory database for LLM agents.","license":"Apache-2.0","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./src/index.ts"},"./agent":{"types":"./dist/agent.d.ts","import":"./dist/agent.js","default":"./src/agent.ts"},"./plugin":{"types":"./dist/plugin.d.ts","import":"./dist/plugin.js","default":"./src/plugin.ts"}},"scripts":{"build":"tsc","prepublishOnly":"npm run build"},"engines":{"node":">=18"},"keywords":["abagraph","memory","knowledge-graph","bitemporal","vector","llm","agent"],"devDependencies":{"typescript":"^5.4.0"},"_id":"@abagraph/client@0.1.0","gitHead":"5b11f72d739c94097e34a7a43b8a62b49b489539","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-PeBUji/H3uz6j8p71wtPbJB0FZOOHgf3Q3oNCDLpJ249KGn1JrE0wlOmYjPjhlhfI3CdCP7B+BTkB8U2NGoReA==","shasum":"818cb65f76d0871571cf3c69dbccd103e6bfe940","tarball":"https://registry.npmjs.org/@abagraph/client/-/client-0.1.0.tgz","fileCount":17,"unpackedSize":71338,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIB6oHNLkpioHpxyqtDHIgqqT5rfeHqb+GrLsDojBMdk0AiEAr73k78MW1i94iVJoHMWeSjO78X60MfqTX7p4/etHZI8="}]},"_npmUser":{"name":"ashby1","email":"ash@abagraph.com"},"directories":{},"maintainers":[{"name":"ashby1","email":"ash@abagraph.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/client_0.1.0_1782734965331_0.45686376133424544"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-29T12:09:25.162Z","0.1.0":"2026-06-29T12:09:25.476Z","modified":"2026-06-29T12:09:25.687Z"},"maintainers":[{"name":"ashby1","email":"ash@abagraph.com"}],"description":"Official TypeScript client for abagraph — the bitemporal graph + vector memory database for LLM agents.","keywords":["abagraph","memory","knowledge-graph","bitemporal","vector","llm","agent"],"license":"Apache-2.0","readme":"# @abagraph/client\n\nOfficial TypeScript client for **abagraph** — the bitemporal graph + vector\nmemory database for LLM agents. It targets the abagraph REST API and reads like\na serverless database driver: create a client once, then call typed methods.\nZero runtime dependencies; uses the built-in global `fetch` (Node >= 18).\n\n## Install\n\n```bash\nnpm i @abagraph/client\n```\n\n## Quickstart\n\n```ts\nimport { createClient } from \"@abagraph/client\";\n\nconst db = createClient({\n  baseUrl: \"https://your.abagraph.com\",\n  apiKey: process.env.ABAGRAPH_KEY, // optional; sent as Authorization: Bearer\n});\n\n// Health check\nawait db.health(); // -> { ok: true }\n\n// Assert a fact (subject – predicate – object)\nconst fact = await db.assert({\n  subject: \"user:alice\",\n  predicate: \"prefers\",\n  object: \"dark-mode\",\n  confidence: 0.9,\n  source: \"settings-page\",\n});\n\n// Query facts back\nconst prefs = await db.query({ subject: \"user:alice\", limit: 20 });\nconsole.log(prefs);\n\n// Goal-directed recall — assemble a context packet for an agent turn\nconst packet = await db.context({\n  goal: \"What are Alice's UI preferences?\",\n  max_facts: 50,\n});\nconsole.log(packet.facts);\n```\n\n### Branches (write isolation + time travel)\n\n```ts\n// Create a branch off the current state\nawait db.branches.create({ name: \"experiment\" });\n\n// Write onto the branch\nawait db.assert(\n  { subject: \"user:alice\", predicate: \"prefers\", object: \"light-mode\" },\n  { branch: \"experiment\" },\n);\n\n// Read the branch\nconst onBranch = await db.query({ subject: \"user:alice\", branch: \"experiment\" });\n\n// Inspect what differs from the parent\nconst diff = await db.branches.diff(\"experiment\");\n\n// Merge the branch into main (or throw it away)\nawait db.branches.promote(\"experiment\");\n// await db.branches.discard(\"experiment\");\n```\n\n### Fact-checking (contradiction detection)\n\n```ts\nconst result = await db.factcheck({\n  subject: \"user:alice\",\n  predicate: \"prefers\",\n});\nconsole.log(`${result.count} contradiction(s)`, result.contradictions);\n```\n\n### Atomic transactions\n\n```ts\nawait db.transact({\n  compares: [],\n  asserts: [{ subject: \"lock:job-1\", predicate: \"held-by\", object: \"worker-7\" }],\n  retracts: [],\n});\n```\n\n## Errors\n\nAny non-2xx response throws an `AbagraphError` carrying the server error\nenvelope:\n\n```ts\nimport { AbagraphError } from \"@abagraph/client\";\n\ntry {\n  await db.retract(\"does-not-exist\");\n} catch (err) {\n  if (err instanceof AbagraphError) {\n    console.error(err.status, err.code, err.message);\n  }\n}\n```\n\n### Agent memory — per-turn wrapper\n\n`createAgentMemory` wraps the base client with frozen-snapshot semantics: load\ncontext **once** at session start (prefix-cache stable), then write facts back\nat the end. A write is persisted to the graph but NOT visible in the current\nsession (`inContext: false`) — the snapshot stays frozen until the next\n`loadContext`.\n\n```ts\nimport { createAgentMemory } from \"@abagraph/client/agent\";\n\nconst mem = createAgentMemory({\n  baseUrl: \"https://your.abagraph.com\",\n  apiKey: process.env.ABAGRAPH_KEY,\n  namespace: \"nas\",\n  agent: \"reels-bot\",\n  defaultBudget: 4096,\n  onLog: (e) => console.error(JSON.stringify(e)), // structured log to stderr\n});\n\n// --- session start ---\nconst ctx = await mem.loadContext(\"plan reels for @maya\", {\n  seeds: [\"Creator:maya\"],\n  budget: 2048,\n});\n// ctx.facts is now the frozen context packet for this session.\n\n// --- agent does its work, then writes back ---\nconst result = await mem.remember([\n  {\n    subject: \"Creator:maya\",\n    predicate: \"audience_age_peak\",\n    object: \"18-24\",\n    confidence: 0.85,\n    why: \"derived from last 30 reels engagement data\",\n  },\n]);\n// result → { persisted: true, inContext: false, ids: [\"...\"] }\n\n// --- sugar: load → run → remember in one call ---\nconst output = await mem.turn(\"plan reels for @maya\", async (context) => {\n  const plan = await myAgent(context);\n  return {\n    result: plan,\n    facts: [{ subject: \"Creator:maya\", predicate: \"latest_plan\", object: plan.id }],\n  };\n});\n```\n\n#### `digest` / `compact` / `enrich` / `consolidate`\n\n```ts\n// Ingest raw content (fire-and-forget async):\nawait mem.digest({ content: sessionTranscript, contentType: \"text/plain\" });\n\n// Compact a fact set to a token budget:\nconst { facts, tokens, dropped } = await mem.compact(ctx.facts ?? [], 1024);\n\n// PII-mask + conflict-check incoming facts before writing:\nconst { facts: clean, masked, conflicts } = await mem.enrich(rawFacts);\n\n// Deduplicate persisted facts and surface contradictions (run periodically):\nconst { collapsed, superseded, conflicts: cnt } = await mem.consolidate();\n```\n\n### Runner-level plugin (ADK style)\n\nInstall **once** at the runner. Individual agents need no extra wiring.\n\n```ts\nimport { memoryPlugin } from \"@abagraph/client/plugin\";\n\nconst plugin = memoryPlugin({\n  baseUrl: \"https://your.abagraph.com\",\n  apiKey: process.env.ABAGRAPH_KEY,\n  namespace: \"nas\",\n  agent: \"reels-bot\",\n});\n\n// In your runner loop:\nconst ctx = await plugin.onSessionStart({ task: \"plan reels for @maya\" });\n// ... run the agent with ctx ...\nplugin.onSessionEnd({ content: sessionTranscript }); // fire-and-forget\n```\n\n`onSessionEnd` returns immediately — write-back is async and does not block the\nnext session. Throw inside `onSessionStart` to short-circuit (e.g., block when\nthe tenant is over quota).\n\n## API surface\n\n| Method | REST endpoint |\n| --- | --- |\n| `health()` | `GET /api/health` |\n| `assert(fact, { branch? })` | `POST /api/facts` |\n| `retract(id)` | `DELETE /api/facts/:id` |\n| `query(params)` | `GET /api/facts` |\n| `transact(body, { branch? })` | `POST /api/transact` |\n| `context(req)` | `POST /api/context` |\n| `search(q)` | `POST /api/search` |\n| `graph()` | `GET /api/graph` |\n| `walk(params)` | `GET /api/walk` |\n| `tenants.{create,list,get,delete}` | `/api/tenants` |\n| `branches.{create,list,get,diff,promote,discard}` | `/api/branches` |\n| `factcheck(params)` | `GET /api/factcheck` |\n| `connect()` | `GET /api/connect` |\n| `digest(req)` | `POST /api/digest` |\n| `compact(req)` | `POST /api/compact` |\n| `enrich(req)` | `POST /api/enrich` |\n| `consolidate()` | `POST /api/consolidate` |\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md","_rev":"1-7a0f57a3d9746c59b05951d70371b2ce"}