![\"polypack\"](\"docs/assets/logo-lockup-dark.svg\"){kind=logo}
\n \n \n
Embedded graph and vector memory for adaptive, local-first apps.
\n\n[](https://www.npmjs.com/package/@0xx0lostcause0xx0/polypack)\n[](https://github.com/imattau/polypack/releases/latest)\n[](https://github.com/imattau/polypack/actions/workflows/ci.yml)\n\nPolypack is an embedded graph and vector database for adaptive, local-first\napplications. It combines property relationships, semantic search, persistent\nactivation, working-memory primitives, and real-time synchronisation across\nTypeScript, Python, and Rust. It runs in Node.js and the browser with pluggable\npersistence (in-memory, filesystem, or OPFS).\n\n## Install\n\n```sh\nnpm install @0xx0lostcause0xx0/polypack\n```\n\nReact is an optional peer dependency and is only required when importing from `@0xx0lostcause0xx0/polypack/react`.\n\nPython and Rust bindings over the same core are published separately:\n\n```sh\npip install polypack-db\n```\n\n```sh\ncargo add polypack-core\n```\n\n## Releases\n\n- **npm package:** [`@0xx0lostcause0xx0/polypack`](https://www.npmjs.com/package/@0xx0lostcause0xx0/polypack)\n is the installable TypeScript/JavaScript distribution for Node.js and browser\n build tooling. [`@0xx0lostcause0xx0/polypack-native`](https://www.npmjs.com/package/@0xx0lostcause0xx0/polypack-native)\n provides NAPI-RS bindings to the native `VectorIndex`/`HNSWIndex`.\n- **PyPI package:** [`polypack-db`](https://pypi.org/project/polypack-db/)\n is the Python distribution, built with maturin/PyO3 over the same Rust core.\n- **crates.io package:** [`polypack-core`](https://crates.io/crates/polypack-core)\n is the portable Rust core (property graph, vector search, persistence)\n underlying the TypeScript native addon and the Python bindings.\n- **GitHub releases:** [release notes, source archives, and tags](https://github.com/imattau/polypack/releases)\n are published from the repository. The current coordinated source version\n is `3.5.0`.\n\nStable GitHub releases run the complete test, build, export, and package checks\nbefore the corresponding packages are submitted to npm, PyPI, and crates.io\nwith provenance/trusted publishing. All three ecosystems are version-locked\ntogether. See the [changelog](CHANGELOG.md) for breaking changes and\nmigration notes.\n\n## Features\n\n- **Property graph** — typed nodes and edges with arbitrary data payloads\n- **LRU working set** — 50K loaded-node limit by default, with explicit restoration from persistence\n- **Vector similarity** — cosine, euclidean, or pluggable distance functions\n- **Pluggable text embeddings** — supply any local or hosted model, with a\n dependency-free 384-dimensional feature-hash provider included by default\n- **Fluent query builder** — filter by type/attribute/edge/range, BFS traversal, vector similarity\n- **Relational extensions** — `pluck`, `aggregate`, `groupAggregate`, `join`, `groupByVector` (clustering)\n- **Edge ownership** — `owned` (cascade delete), `shared` (orphan detection), `reference` (no-op)\n- **Reactive** — RxJS change events, batching, React hooks\n- **Pluggable persistence** — MemoryAdapter, BinaryStoreAdapter (MessagePack + WAL), build your own\n- **Database core** — atomic transactions, revisions, conditional writes, patches, schema hooks, and resource limits\n- **Capability checks** — inspect adapter guarantees and reject configurations that require unsupported durability, indexing, concurrency, or vector-search features\n- **Operational durability** — checkpoint/backup/verification APIs, durable logical mutation logs, cursors, and idempotent operation IDs\n- **Schema migrations** — contiguous, validated, retry-safe application migrations with dry runs, resume cursors, and progress reporting\n- **Explainable queries** — persisted and hot-query plans with index selection, estimated cost, and operational metrics\n- **Configurable indexes** — compound and unique node-data indexes with persisted Python index metadata\n- **Cross-language contract** — shared conformance fixtures and compatibility levels for TypeScript, Rust, and Python\n- **Persisted queries** — asynchronous filtering, ordering, pagination, and similarity across the full backing store without loading the result set into the hot cache\n- **Adaptive memory** — durable, decayed relevance (`score`/`importance`/`inhibition`) per node with per-context activation lenses, spreading activation over edges, semantic pulses, a budgeted/diversity-aware working-memory set, memory classes with differentiated decay, confidence/provenance fields, contradiction (`supersede`) and consolidation (`consolidate`) primitives, and feedback-driven learned scoring weights — synced additively\n- **Real-time sync** — acknowledgements, retry, deduplication, reconnect recovery, and echo suppression\n\nFor scale limits and reproducible 100K/1M/10M-node characterization, see the\n[scale benchmark](benchmarks/scale-characterization.md). Its default vector\nscope is capped at 100K for practical 10M-node storage and graph runs; full\nvector indexing is an explicit opt-in.\n\n## Quick start\n\n```typescript\nimport { PolyGraph, MemoryAdapter } from '@0xx0lostcause0xx0/polypack'\n\nconst graph = new PolyGraph()\n\n// Add nodes with vectors\ngraph.addNode({\n id: 'doc_1',\n type: 'document',\n data: { title: 'Quantum Computing' },\n vector: new Float64Array([0.95, 0.20, 0.10]),\n insertedAt: Date.now(),\n updatedAt: Date.now(),\n})\n\n// Or generate vectors from text with the default model-free provider\nawait graph.addNodeWithEmbedding({\n id: 'doc-2',\n type: 'document',\n data: { title: 'Graph search' },\n insertedAt: Date.now(),\n updatedAt: Date.now(),\n}, 'Property graphs with vector similarity search')\n\nconst textMatches = await graph.queryText('semantic graph search', 0.1, 10)\ntextMatches.toArray()\n\n// Query the complete persisted store without warming the hot cache\nconst recentPosts = await graph.queryPersisted()\n .whereNodeType('document')\n .orderBy('updatedAt', 'desc')\n .limit(20)\n .toArray()\n\n// Search by similarity\ngraph.query()\n .whereNodeType('document')\n .similarTo([0.90, 0.30, 0.10], 0.5, 5)\n .toArray()\n\n// Traverse edges\ngraph.query()\n .where('title', 'Quantum Computing')\n .traverse('REFERENCES', 3, 'out')\n .toArray()\n\n// Aggregate\ngraph.query()\n .whereNodeType('book')\n .aggregate('price', 'avg')\n\n// Group by vector cluster\ngraph.query()\n .whereNodeType('product')\n .groupByVector(\n [{ key: 'electronics', centroid: [0.9, 0.1] }],\n 'price', 'avg', 0.4,\n )\n```\n\n## Packages\n\n| Subpath | Contents |\n|---------|----------|\n| `@0xx0lostcause0xx0/polypack` | Core: PolyGraph, VectorIndex, GraphQuery, PersistedGraphQuery, MemoryAdapter |\n| `@0xx0lostcause0xx0/polypack/persistence` | Platform-neutral persistence: adapters, `FileIO` types |\n| `@0xx0lostcause0xx0/polypack/persistence/node` | BinaryStoreAdapter + `NodeFileIO` for the filesystem |\n| `@0xx0lostcause0xx0/polypack/persistence/opfs` | BinaryStoreAdapter + `OPFSFileIO` for the browser |\n| `@0xx0lostcause0xx0/polypack/react` | React hooks: `useGraphQuery`, `useLiveQuery`, `useWorkingMemory` |\n| `@0xx0lostcause0xx0/polypack/activation` | Adaptive memory: `ActivationEngine` (inhibition, per-context activation, budgeted/diverse `workingMemory`, learned weights via `recordFeedback`), `mergeActivation`, activation config types |\n| `@0xx0lostcause0xx0/polypack/sync` | Sync layer: OpLog, SyncAdapter, SyncClient, SyncServer |\n| `@0xx0lostcause0xx0/polypack-native` | Separate package: NAPI-RS bindings for native `VectorIndex`/`HNSWIndex` over the Rust core |\n| `polypack-db` (PyPI) | Separate package: PyO3/maturin bindings exposing `PolyGraph`, `GraphQuery`, `PersistedGraphQuery`, and vector indexes to Python — see [python/README.md](python/README.md) |\n| `polypack-core` (crates.io) | Separate package: the portable Rust core (property graph, vector search, persistence) shared by the TypeScript native addon and the Python bindings |\n\nSee the complete [API reference](docs/API.md), including persistence, React,\nsync, lifecycle, ownership, and error contracts.\n\nThe Python binding has a separate, idiomatic API with `snake_case` method names.\nSee the [Python API guide](python/README.md) for `PolyGraph`, hot-cache\n`GraphQuery`, native storage-level `query_persisted()`, vector indexes, and\nbinding-specific behavior.\n\n## Requirements\n\n- Node.js 18 or newer when used in Node.js.\n- A browser with the File System Access API (OPFS) when using\n `@0xx0lostcause0xx0/polypack/persistence/opfs`.\n- Equal vector dimensions for similarity operations; mismatches throw `RangeError`.\n\nPolypack is distributed as native ES modules.\n\n## Contributing and security\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development instructions. Please\nreport vulnerabilities according to [SECURITY.md](SECURITY.md).\n\n## License\n\nMIT\n","readmeFilename":"README.md"}