Palari Brain

Long-term memory for assistants, grounded in the conversation that created it.

Try it · Use the core · Integration guide · Documentation · Issues

An assistant remembers that your bicycle is blue. Later, you correct it to green. Then you ask it to forget. The next answer should reflect each change, and you should be able to inspect the source behind it.

Palari stores exact dialogue with its speaker, time, and private scope. Retrieval returns to those records. Corrections preserve what was said and when; forgetting removes the selected records and invalidates their dependent memory state. You choose the model, the retrieval strategy, and whether to use a summary.

An index may locate evidence. It may never become evidence.

Try it locally

Requires Node.js 22.5+. This example uses a temporary local store and scripted answers. No API key, model download, or paid provider is needed.

git clone https://github.com/CoyStan/palari-brain.git
cd palari-brain
npm install --omit=optional
npm run quickstart:simple

Remember: My bicycle is blue.
Correct: Correction: my bicycle is green.
Read: original and correction remain separately attributable.
Forget: no evidence returned; no answer provider called.

Read the complete example, or run npm run quickstart to see the same memory journey with incremental reduction. The optional native dependency accelerates eligible semantic searches; the journal example works without it.

What makes Palari different

A valid citation proves where the text came from. It does not prove that the model interpreted it correctly. Palari keeps that distinction explicit.

Use the core

The code below runs from a checkout as node --input-type=module. It stores, finds, reads, and deletes a memory without calling a model.

import { randomUUID } from 'node:crypto'
import {
  createPalariBrain,
  forgetMemories,
  ingestChatTurn,
} from './src/core.mjs'

const brain = await createPalariBrain({
  memoryEnabled: true,
  memoryRootDir: './.palari-alpha/readme-demo',
  workspaceId: 'my-app',
  digestMode: 'off',
})
const scope = { palariId: 'assistant', userId: 'alice' }

try {
  const stored = await ingestChatTurn(brain, {
    ...scope,
    retention: 'durable',
    sourceMessageId: randomUUID(), // One new interaction per demo run.
    eventAt: '2026-09-06T09:00:00Z',
    userMessage: 'My bicycle is blue.',
    assistantMessage: '',
  })

  const found = brain.exploreFind(scope, {
    phrase: 'bicycle',
    ranked: true,
  })
  const evidence = brain.exploreRead(scope, {
    evidenceIds: found.matches.map(row => row.evidenceId),
  })
  console.log(evidence.messages.map(row => row.text))
  // ['My bicycle is blue.']

  forgetMemories(brain, stored.written.map(row => row.id), scope)
} finally {
  brain.close()
}

Your application supplies authenticated scope and decides what to retain. To record a correction, ingest the user's new corrective statement with a new message ID. In journal mode, the answer policy interprets the chronology.

When installed as a package from this revision, import from palari-brain/core and palari-brain/answers. This README describes main. The older v0.1.0-alpha.1 release predates these entrypoints. The package is not published to the npm registry.

Choose how much memory machinery you need

Host-approved dialogue
         │
         ▼
 Canonical journal ────────────── exact scoped reads
         │                              ▲
         ├── optional digest            │
         └── retrieval indexes ─────────┘
                                        │
                                        ▼
                              answer + checked citations

Start with the journal. Add derived components when your application needs them.

The integration guide covers the callback contract, limits, and configuration. Existing root exports remain supported.

Project memory from multiple sources

The optional source-memory API keeps documents separate from user speech. Claims cite exact source versions; updates and revocations exclude dependent claims until they are checked again. Alternative claims remain visible, and known copies share an origin count.

npm run quickstart:sources

The source-memory guide covers admission, provisional claims, permissions, deletion and the injected answer callback. The example uses an explicit approval policy; it does not claim automatic conflict resolution.

What is proven so far

Palari is an alpha library with local SQLite storage and injected providers. It is not a hosted memory service. The core does not call a model on its own.

The offline examples and contract tests exercise admission, attribution, scope, retrieval, correction, deletion, and citation validation. The scripted comparison covers 12 combinations of journal/digest modes, answer paths, and memory events. It checks integration behavior, not model reasoning quality.

Real-model comparisons on previously unused histories remain open. We have not established an advantage over long context or a simpler profile-plus-search system, and existing diagnostics do not establish 100M-token capacity. Scoped BM25 has a per-query indexing cost; maximum-chunk retrieval remains experimental. See current status and evaluation notes.

npm test                      # Focused, provider-free contracts
npm run test:legacy           # Broader compatibility suite
npm run quickstart           # Incremental digest journey
npm run quickstart:simple    # Journal-only journey
npm run alpha:compare-simple # Scripted comparison, no provider calls
npm run package:check        # Offline install and public entrypoints

Find your next step

Help build it

Useful contributions start with a concrete memory journey: what was stored, what was asked later, and what should happen after a correction or deletion. Open an issue with a minimal, synthetic example, or send a focused pull request. Include the expected behavior and the checks you ran. Never include someone's private conversation.

Read the agent charter for the repository's development boundaries.

MIT licensed. Original Palari artwork ships under the same license.