Home

polypack

Embedded graph and vector memory for adaptive, local-first apps.

Polypack is an embedded graph and vector database for adaptive, local-first applications. It combines property relationships, semantic search, persistent activation, working-memory primitives, and real-time synchronisation across TypeScript, Python, and Rust. It runs in Node.js and the browser with pluggable persistence (in-memory, filesystem, or OPFS).

This wiki is a supplement to the docs that live in the repository itself. Anything version-specific — the API reference, the changelog, release process — is kept in-repo so it stays in lockstep with the code; this wiki is for higher-level orientation and notes that don't belong in a source file.

Install

npm install @0xx0lostcause0xx0/polypack

pip install polypack-db

cargo add polypack-core

React is an optional peer dependency, only required when importing from @0xx0lostcause0xx0/polypack/react.

Quick start

import { PolyGraph, MemoryAdapter } from '@0xx0lostcause0xx0/polypack'

const graph = new PolyGraph()

graph.addNode({
  id: 'doc_1',
  type: 'document',
  data: { title: 'Quantum Computing' },
  vector: new Float64Array([0.95, 0.20, 0.10]),
  insertedAt: Date.now(),
  updatedAt: Date.now(),
})

// Search by similarity
graph.query()
  .whereNodeType('document')
  .similarTo([0.90, 0.30, 0.10], 0.5, 5)
  .toArray()

See the README for the full quick-start walkthrough (text embeddings, persisted queries, traversal, aggregation, and clustering).

Highlights

• Property graph — typed nodes and edges with arbitrary data payloads, ownership-based cascade rules, and reactive change events
• Query builder — filter by type/attribute/edge/range, BFS traversal, vector similarity, aggregation, and clustering, both over the loaded working set and the complete persisted store
• Vector search & embeddings — cosine/euclidean or pluggable distance functions, exact and HNSW indexes, pluggable text embeddings with a dependency-free default provider
• Persistence — in-memory, filesystem, or OPFS adapters, with a MessagePack + WAL binary store you can build your own adapter against
• Database core — atomic transactions, revisions, conditional writes, patches, resource limits, secondary indexes, and adapter capability checks
• Schema migrations — contiguous, validated, retry-safe application migrations with dry runs and resumable progress
• Adaptive memory — durable, decayed relevance (score/importance/inhibition) per node, spreading activation over edges, semantic pulses, a budgeted working-memory set, and feedback-driven learned scoring weights
• Real-time sync — acknowledgements, retry, deduplication, reconnect recovery, and echo suppression
• React integration — hooks for live queries and working memory
• Cross-language contract — shared conformance fixtures across TypeScript, Rust, and Python so all three bindings behave identically

Related projects

• polypack-mcp — an MCP server that exposes polypack's adaptive-memory layer as tools for Claude, Codex, and other MCP clients.
• Four-Agents-Polypack — a research experiment running four independent LLM agents that collaborate solely through a shared polypack-mcp memory store, with no orchestrator or direct messaging.

Where things live

Looking for...	Go to
Full feature list & quick start	README
API reference (TypeScript + Python notes)	docs/API.md
Python-specific API	python/README.md
Release history & migration notes	CHANGELOG.md
How releases are cut & published	RELEASING.md
Scale benchmarks (100K/1M/10M nodes)	benchmarks/scale-characterization.md
Contributing, dev setup	CONTRIBUTING.md
Bug reports & feature requests	Issues
Packages	npm · PyPI · crates.io

License

MIT