PSON5 v0.2.0
Personalization infrastructure v0.2.0 · MIT · TypeScript

Personalization your agents can actually reason about.

PSON5 is an open-source personalization infrastructure and .pson file format. It keeps what the user said, what the model inferred, and what the simulator predicted as three separate, auditable things — so agents can plan, explain, and fail gracefully on top of them.

Star on GitHub Read the docs
packages on npm
15
median merge · 5000 traits
3.2ms
license
MIT
01 · Problem

Agent memory is opaque, non-portable, and collapses epistemic layers.

Vendor memory features store free-form notes derived by the model itself. You cannot, in general, tell which entries are direct user statements and which are the model's guesses about you. The same ambiguity propagates to every downstream agent.

Without PSON5
  • Memory is one blob. Evidence and inference live in the same sentence.
  • Predictions leak back into "facts" on the next turn.
  • No confidence, no provenance, no decay.
  • Portable only if you build the portability yourself.
  • Audit trail = nothing.
With PSON5
  • Three separate layers by construction.
  • Every inferred claim carries confidence and evidence refs.
  • Simulations are never written back as facts.
  • .pson moves between models, tenants, and stores.
  • Agents produce reasoning traces alongside predictions.
02 · The three-layer invariant

What you said. What we inferred. What we predict.

This separation is the hard constraint of the project. Every engine, every storage adapter, every SDK call is designed to keep these three layers from collapsing. Scope §29, the "Final Constraint."

01 observed

Direct user statements or direct behavioural evidence. Content this layer contains was said or demonstrated by the user.

  • Sources: chat, forms, instrumented actions
  • Never generated
  • Addressable, auditable, user-editable
02 inferred

Traits, tendencies, heuristics. Every entry carries a confidence score and references the observed evidence that supports it.

  • Confidence required on every claim
  • Evidence references required
  • Decays over time unless re-validated
03 simulated

Scenario-specific predictions generated in response to a query. Never written back as observed or inferred.

  • Includes prediction, confidence, reasoning, caveats
  • Ephemeral by default
  • Consent-scoped
03 · Pipeline

Six cooperating engines, one layered profile.

Signals flow in through the acquisition engine, get structured by modeling, simulated on demand, tracked as state, related through the graph, and persisted via serialization. Every hop respects the layer invariant.

  1. 01
    Acquisition
    Collect signals via direct input, adaptive prompts, scenario probes, or behavioural capture. Owns follow-up generation, fatigue detection, confidence-gap targeting, and contradiction probing.
  2. 02
    Modeling
    Three subsystems: trait extractor (stable attributes), pattern miner (repeated decisions), heuristic builder (conditional rules). Every derived claim is labelled with confidence + evidence refs.
  3. 03
    State
    Transient conditions — focused, distracted, stressed, motivated — with trigger patterns, behaviour shifts, duration tendencies, recovery signals.
  4. 04
    Graph
    Nodes and edges over learned entities. Supports causal and correlational links, traversal queries. Neo4j adapter ships built-in.
  5. 05
    Simulation
    Decision simulation, response simulation, action likelihood, counterfactual comparison — each with an explicit reasoning trace and caveats block alongside the prediction.
  6. 06
    Serialization
    Portable .pson documents. Versioned, schema-validated, consent-scoped, encryption-aware. Roundtrips in under 1.3 ms at 1000-fact scale.
04 · Install

Three lines, any model provider.

The SDK ships with first-class adapters for OpenAI, Anthropic, and any OpenAI-compatible endpoint. Plug in a custom ProviderAdapter if you're running your own.

npm

Install the SDK

npm install @pson5/sdk
typescript

Build a profile

import { createPsonSdk } from "@pson5/sdk";

const sdk = createPsonSdk({ provider: "anthropic" });

const profile = await sdk.observe({
  domain: "core",
  fact: "primary_language",
  value: "rust"
});

const traits = await sdk.infer(profile);
const decision = await sdk.simulate({
  profile,
  scenario: "series_a_founding_engineer_offer"
});
cli

Or stay in the terminal

npx @pson5/cli init ./profile.pson
npx @pson5/cli ask --domain core
npx @pson5/cli simulate \
  --profile ./profile.pson \
  --scenario "series_a_offer"
05 · Packages

Fifteen packages on npm, all MIT.

The SDK pulls in whichever engines you need. Everything is also addressable individually — use the trait extractor without the simulator, the graph without the SDK, whatever fits.

SDK

@pson5/sdk

Primary TypeScript SDK. Observe, infer, simulate, project context for an agent. This is what most integrations use.

npm source
CLI

@pson5/cli

Terminal interface — init, ask, infer, simulate, project, explain. Typed error codes, shell completion, readable output.

npm source
Foundation

@pson5/core-types

Single source of interface truth. All TypeScript types and contracts shared by every package.

npm source
Foundation

@pson5/schemas

JSON Schemas for .pson documents. Validation, migration, drift detection.

npm source
Foundation

@pson5/privacy

Redaction, consent enforcement, provider-policy helpers. Keeps restricted fields out of simulation output.

npm source
Engine

@pson5/acquisition-engine

Adaptive question flow, follow-up generation, fatigue detection, contradiction probing. Works with or without a domain registry.

npm source
Engine

@pson5/modeling-engine

Rules-first trait extractor, pattern miner, heuristic builder. Every output is confidence-annotated and evidence-linked.

npm source
Engine

@pson5/simulation-engine

Scenario simulation: decision, response, action likelihood, counterfactual. Emits reasoning trace + caveats alongside every prediction.

npm source
Engine

@pson5/state-engine

Dynamic state derivation — focused, distracted, stressed, motivated — with trigger patterns and recovery signals.

npm source
Engine

@pson5/graph-engine

Knowledge-graph construction + explainability helpers. Deterministic derivation so two runs over the same data produce identical graphs.

npm source
Engine

@pson5/serialization-engine

.pson init, import/export, storage adapters, persistence. Roundtrips 1000 facts in ~1.3 ms.

npm source
Integration

@pson5/provider-engine

Model-agnostic ProviderAdapter registry. OpenAI, Anthropic, and OpenAI-compatible ship built-in.

npm source
Integration

@pson5/agent-context

Agent-safe projection layer. Redacted, consent-scoped summary of a profile — never exposes raw internals to the agent.

npm source
Storage

@pson5/neo4j-store

Neo4j persistence + graph sync. Bidirectional with the graph engine; supports Cypher traversal.

npm source
Storage

@pson5/postgres-store

Postgres-oriented repository + schema helpers. Use with pgvector for embedding support.

npm source

Full org on npm: npmjs.com/org/pson5

Each package ships with its own README, typed entry points, and keeps its public surface small. The full monorepo lives at github.com/fredabila/pson5 .

06 · Agent integration

Point any model at the profile — it never reads raw internals.

The SDK exposes PSON operations as tool definitions consumable by Claude, GPT, and OpenAI-compatible models. The agent calls projectContext(scope) and receives a redacted, consent-scoped summary with a reasoning trace. Raw evidence never leaks. 

import Anthropic from "@anthropic-ai/sdk";
import { buildAgentTools } from "@pson5/sdk/agent-tools";

const client = new Anthropic();
const tools = buildAgentTools(sdk, { scope: "core" });

const response = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  tools,
  messages: [
    { role: "user", content: "Should I take the Series A offer?" }
  ]
});

// The agent calls pson_project, pson_simulate, pson_explain as tools.
// Every simulation comes back with reasoning + caveats.
07 · Principles

Probabilistic. Consent-first. Explainable.

Probabilistic over absolute

Every trait carries confidence. Predictions carry confidence. Low-confidence is marked, not hidden.

Consent-first data collection

Scopes, restricted fields, and revocation are in the data model, not a side table.

Minimal data for the use case

Domain modules activate only when you need them. No silent over-collection.

Portable profiles

A .pson file moves between models, tenants, and backends unchanged.

Modular domain expansion

Productivity, education, finance, health, social — and custom domains under your own namespace.

Layer separation as law

Observed, inferred, simulated remain distinct across every engine, every store, every API surface.

Ship it

Start with @pson5/sdk.
Skim the scope doc. Open an issue.

v0.2.0 is the first production-oriented release. PRs welcome. Scope doc is the canonical spec — every engine respects it.

Open the repo Open the docs