Paw Memory

Memory that keeps its sources.

Evidence-first memory for agents · TypeScript core · Persistent PostgreSQL SDK

English · 简体中文

Quick start · Benchmarks · Architecture · SDK guide · Pi adapter

Paw Memory stores original conversation turns, retrieves relevant evidence, and preserves who said what when memory reaches an agent. Derived cards help locate information; the original source remains the evidence.

From the repository root, with Bun 1.3.14 and Docker Compose (or an existing PostgreSQL 16+ server):

bun install --frozen-lockfile
cp .env.example .env
docker compose up -d --wait
bun run db:migrate
bun run example

The example writes a conversation, closes its connection pool, reconnects, and recalls the original evidence. No model API key or Python environment is needed; PostgreSQL must be running.

Using an existing database? Set DATABASE_URL in .env, skip the Docker command, and run the migration. The Compose credentials are for local development. See PostgreSQL setup for schema permissions, tests and upgrading from the SQLite snapshot.

import { createMemory, renderMemoryContext } from "@paw/memory";

const memory = createMemory({
  connectionString: process.env.DATABASE_URL!,
  scope: {
    tenantId: "local",
    userId: "alice",
    workspaceId: "personal",
    repositoryId: "travel",
  },
});

await memory.retain({
  conversationId: "trip-1",
  turns: [{
    sequence: 1,
    role: "user",
    content: "I stayed in Kyoto for seven days.",
    createdAt: "2026-08-01T00:00:00.000Z",
  }],
});

const result = await memory.recall("How long was my Kyoto trip?");
console.log(renderMemoryContext(result));
await memory.close();

@paw/memory resolves through this repository's workspace. It is not yet an npm-published package. For optional model extraction, see the runnable example and SDK guide.

flowchart TB
    A[Conversation turns] --> B[Validate and retain]
    B --> C[(L0 · Original evidence)]
    B --> D[L1 · Navigation cards]
    D -. Source references .-> C
    Q[Agent question] --> R[Scoped retrieval and source lock]
    C --> R
    D --> R
    R --> E[Evidence packet · Roles, sources and coverage]
    E --> H[Host answer model]
    classDef source fill:#e7f7f1,stroke:#169b77,color:#123c32
    classDef engine fill:#edf3ff,stroke:#6283c6,color:#243c64
    class C,D source
    class B,R,E engine

Write once, keep the source. Original turns are L0 evidence; extracted cards are L1 navigation. Corrections are new turns instead of silent source overwrites. During retrieval, source locks and authority checks constrain the evidence passed to the host. The host owns the final answer model.

The original full Paw v77 system reported 454 / 500 correct (90.80%) on a LongMemEval-S development regression using the AMB evaluation integration.

This is a historical full-system result, not a measurement of this minimal repository or its PostgreSQL SDK. Public questions were used during development; it is not an official leaderboard submission.

An agent calls recall before answering and retain after an exchange. The Pi adapter demonstrates that lifecycle through a Bun subprocess. Read the architecture guide to replace storage or integrate another host.

bun run check

Set TEST_DATABASE_URL to a development/test database (.env.example includes the local Compose URL). The validation suite has 404 tests: 384 core tests and 20 SDK/Pi tests, plus lint and type checks. PostgreSQL tests exercise real connections, competing writes, rollback, scope isolation and Pi subprocess persistence. Tests do not call paid models.

CI checks the core on Windows/Linux, runs PostgreSQL integration tests on Linux, and checks the standalone core separately. Local PostgreSQL integration was verified on Windows. A live-model Pi conversation has not been tested. bun run check:core needs no database.

• The SDK is validated with Bun and exports TypeScript source. PostgreSQL 16+ is required.
• PostgreSQL retrieval is lexical and append-only. Embeddings, robust paraphrase matching and automatic update/merge policies are not included.
• Conversation text is stored as supplied. The host owns authentication, privacy controls and backups.

See SDK usage and limits before choosing a production retrieval adapter.

MIT © 2026 Paw Memory contributors. Packages have private: true to prevent accidental npm publication; this does not restrict use under the MIT license.