{"_id":"@blackunicorn/bonklm-purple-hippo","_rev":"2-8a08dbb1964b758038f5977f219054f6","name":"@blackunicorn/bonklm-purple-hippo","dist-tags":{"probe":"1.0.4-probe.5","latest":"1.0.4-probe.5"},"versions":{"1.0.4-probe.5":{"name":"@blackunicorn/bonklm-purple-hippo","version":"1.0.4-probe.5","keywords":["zep","memory","llm","guardrails","security","ai-safety","bonklm"],"author":{"name":"BlackUnicorn","email":"info@blackunicorn.tech"},"license":"Apache-2.0","_id":"@blackunicorn/bonklm-purple-hippo@1.0.4-probe.5","maintainers":[{"name":"schenlong","email":"julien@blackunicorn.tech"}],"homepage":"https://github.com/BlackUnicornSecurity/bonklm#readme","bugs":{"url":"https://github.com/BlackUnicornSecurity/bonklm/issues"},"dist":{"shasum":"01c87cbf4dd8f7c9f76364f140a587adfbaa1c1a","tarball":"https://registry.npmjs.org/@blackunicorn/bonklm-purple-hippo/-/bonklm-purple-hippo-1.0.4-probe.5.tgz","fileCount":15,"integrity":"sha512-cTUzQ6CFZTA181VQv3OFf632nVWb/QdSWNTFDqTsStjDVdF14iglcb+nADLzsxZMwh82tv5wjcxlPUFXUVsbZg==","signatures":[{"sig":"MEYCIQDur9vpRqGQnujl8zVWsfznRurvn2lQ0dssegitNg/08gIhAJMK+HpFMVsBh42DT44sCfX3x1/mU8PzpcAS0sz4qKW5","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":51018},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=20.4.0"},"exports":{".":{"bun":"./dist/index.js","deno":"./dist/index.js","types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js","workerd":"./dist/index.js"}},"gitHead":"bb263d620ebdbb647bc506b3facbb6a6814f84d7","scripts":{"dev":"tsc --watch","test":"vitest","build":"tsc","clean":"rm -rf dist","test:types":"tsd","test:coverage":"vitest --coverage"},"_npmUser":{"name":"schenlong","email":"julien@blackunicorn.tech"},"repository":{"url":"git+https://github.com/BlackUnicornSecurity/bonklm.git","type":"git","directory":"packages/zep-connector"},"_npmVersion":"11.5.1","description":"Zep memory-client connector for BonkLM — wraps Zep thread.addMessages/getUserContext + graph.add/search with sealed write + composed-context recall validation","directories":{},"_nodeVersion":"25.2.1","dependencies":{"@blackunicorn/bonklm":"workspace:*","@blackunicorn/bonklm-memory-utils":"workspace:*"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.10","typescript":"^5.3.3","@vitest/coverage-v8":"^4.1.10"},"peerDependencies":{"@getzep/zep-cloud":"^3.0.0"},"peerDependenciesMeta":{"@getzep/zep-cloud":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/bonklm-purple-hippo_1.0.4-probe.5_1786901263307_0.9665787863390547","host":"s3://npm-registry-packages-npm-production"},"deprecated":"screening differential probe — superseded, ignore"}},"time":{"created":"2026-08-16T17:27:43.123Z","modified":"2026-08-16T17:33:05.597Z","1.0.4-probe.5":"2026-08-16T17:27:43.441Z"},"bugs":{"url":"https://github.com/BlackUnicornSecurity/bonklm/issues"},"author":{"name":"BlackUnicorn","email":"info@blackunicorn.tech"},"license":"Apache-2.0","homepage":"https://github.com/BlackUnicornSecurity/bonklm#readme","keywords":["zep","memory","llm","guardrails","security","ai-safety","bonklm"],"repository":{"url":"git+https://github.com/BlackUnicornSecurity/bonklm.git","type":"git","directory":"packages/zep-connector"},"description":"Zep memory-client connector for BonkLM — wraps Zep thread.addMessages/getUserContext + graph.add/search with sealed write + composed-context recall validation","maintainers":[{"name":"schenlong","email":"julien@blackunicorn.tech"}],"readme":"# @blackunicorn/bonklm-zep\n\n> Zep memory-client connector for BonkLM — wraps Zep `thread.addMessages` /\n> `thread.getUserContext` + `graph.add` / `graph.search` with sealed write + composed-context recall\n> validation.\n\n## Overview\n\nThis package wraps the [`@getzep/zep-cloud`](https://www.npmjs.com/package/@getzep/zep-cloud) SDK\nwith a top-level `Proxy` that intercepts `.thread` and `.graph` accesses and applies BonkLM at the\nmethod level. Writes fire the `memory_write` surface; recall paths fire `composed_context`\npost-call. Tenant scoping is enforced on `graph.*` by overwriting `graphId` with `getTenantId(ctx)`\nand stripping the bypass fields `graphIds`, `userId`, `userIds`, `sessionId`.\n\nThe outer proxy is **fail-closed**: unknown top-level callable namespaces throw\n`ConnectorValidationError` so a future Zep SDK addition (e.g. `client.users`) cannot silently bypass\ntenant scoping.\n\n## Installation\n\n```bash\npnpm add @blackunicorn/bonklm-zep @blackunicorn/bonklm @getzep/zep-cloud\n```\n\n## Peer Dependencies\n\n| Package             | Version    |\n| ------------------- | ---------- |\n| `@getzep/zep-cloud` | `^3.0.0`   |\n| Node.js             | `>=20.4.0` |\n\n## Quick Start\n\n```typescript\nimport { ZepClient } from '@getzep/zep-cloud';\nimport { GuardrailEngine, PromptInjectionValidator } from '@blackunicorn/bonklm';\nimport { wrapZepClient } from '@blackunicorn/bonklm-zep';\n\nconst validators = [new PromptInjectionValidator()];\nconst engine = new GuardrailEngine({ validators });\nconst client = new ZepClient({ apiKey: process.env.ZEP_API_KEY });\n\nconst guarded = wrapZepClient(client, engine, {\n  getTenantId: ctx => ctx.userId, // REQUIRED — must be a function\n  getSessionContext: () => requestLocal.get('session'),\n  validators\n});\n\nawait guarded.thread.addMessages({ threadId: 't-1', messages: [{ role: 'user', content: 'hi' }] });\nawait guarded.graph.search({ graphId: 'IGNORED', query: '...' });\n//                                   ^^^^^^^ overwritten with getTenantId(ctx)\n```\n\n## API Reference\n\n### `wrapZepClient(client, engine, options)`\n\nCanonical-shape factory (ADR shape #2). Returns a `Proxy` over the Zep client preserving its\ninterface; intercepts `.thread.*` and `.graph.*` accesses.\n\n- `client` — a `ZepClient` instance.\n- `engine` — a `GuardrailEngine` owning the validator chain.\n- `options: WrapMemoryClientOptions` — `getTenantId` REQUIRED; non-function values throw\n  `ConnectorValidationError`.\n\n### `buildZepAdapter(getTenantId)`\n\nReturns the `MemoryAdapter` bound to a `getTenantId` callback. Exposed for advanced callers\ncomposing custom flows over `@blackunicorn/bonklm-memory-utils`.\n\n### `ConnectorValidationError`\n\nRe-exported from `@blackunicorn/bonklm/core/connector-utils`.\n\n### Wrapped namespaces and methods\n\nTop-level allowlist: `thread`, `graph`. Method routing:\n\n| Zep method              | Surface                        | Notes                                                                 |\n| ----------------------- | ------------------------------ | --------------------------------------------------------------------- |\n| `thread.addMessages`    | `memory_write`                 | Validates `messages[].content`.                                       |\n| `thread.getUserContext` | `composed_context` (post-call) | Validates `context` + `messages[].content`.                           |\n| `graph.add`             | `memory_write`                 | Validates `data` + `episodes[].content`; rewrites `graphId`.          |\n| `graph.search`          | `composed_context` (post-call) | Rewrites `graphId`; validates `episodes` / `facts` / `nodes` entries. |\n\n## Threat Surfaces Covered\n\nSee [`docs/user/threat-surfaces.md`](../../docs/user/threat-surfaces.md) for the 7-surface taxonomy.\n\n- **`memory_write`** — `thread.addMessages`, `graph.add`.\n- **`composed_context`** — `thread.getUserContext`, `graph.search` (post-call validation of the\n  recall blob).\n\nNot covered: `text_input` / `text_output` / `tool_call` / `retrieved_doc` / `audio_partial`. The\n`wrapZepGraphRetriever` graph-as-retrieved-docs factory documented in `connector-style-guide.md` is\nillustrative-only and **not exported** by this package.\n\n## Limitations\n\n- Methods outside the routed set (`addMessages`, `getUserContext`, `add`, `search`) pass through\n  unwrapped within an allowlisted namespace.\n- `thread.*` scoping currently relies on caller-supplied `threadId`/`sessionId`; the adapter does\n  NOT rewrite thread IDs. `graph.*` is where the tenant-scope rewrite happens. `thread.addMessages`\n  is routed for content validation (`memory_write` surface) but the adapter intentionally does NOT\n  enforce a tenant-derived `threadId` — applications must enforce that contract at their call sites.\n  Tracked as a v1.0.1 design discussion: whether the adapter should add `rewriteArgs` for the\n  `thread` namespace analogous to `graph.*` (defaults to opt-in to avoid breaking callers that\n  derive threadId from external systems).\n- Tenant scoping only neutralizes the documented bypass fields (`graphIds`, `userId`, `userIds`,\n  `sessionId`). New scoping fields added by Zep in future SDK versions need an explicit update.\n- Unknown TOP-level callable namespaces fail closed — a Zep SDK upgrade adding a new client\n  namespace will throw until added to the allowlist or passthrough set.\n- No CHANGELOG file ships with this package — see git history.\n\n## Related\n\n- [`@blackunicorn/bonklm-mem0`](../mem0-connector/) — Mem0 memory client.\n- [`@blackunicorn/bonklm-letta`](../letta-connector/) — Letta (MemGPT) memory client.\n- [`@blackunicorn/bonklm-memory-utils`](../memory-utils/) — shared `wrapMemoryClient` +\n  `MemoryAdapter` types this connector builds on.\n\n## License\n\n[Apache-2.0](./LICENSE) © 2026 BlackUnicorn\n","readmeFilename":"README.md"}