Memory

particle-academy/prism-memory

Prism Memory stores what was said in a conversation and retrieves the records that bear on a new question, ranked by meaning and, optionally, by how recent they are. Use it with a Harness thread or on its own to select context without sending the complete conversation on every turn.

The PHP package is a complete memory layer: it embeds through Prism, stores in your database, queues the embedding work and fits recall to a token budget. The TypeScript and Python packages provide the storage contract, vectors, ranking and an in-memory store. They do not embed text: you supply the vectors from your own embeddings call.

Installation#

composer require particle-academy/prism-memory
php artisan migrate

npm install @particle-academy/prism-memory

pip install prism-ai-memory

In PHP the memory_vectors migration is loaded automatically, so migrate is the only setup step. No Redis, vector database or queue worker is required.

Configuration (PHP)#

Publish the config file to change the defaults:

php artisan vendor:publish --tag=memory-config

Postgres and pgvector#

The database driver is linear in the size of a collection. Past roughly twenty thousand memories in one collection, switch to pgvector:

php artisan vendor:publish --tag=memory-pgvector-migrations
php artisan migrate

Then set MEMORY_STORE=pgvector. The migration runs CREATE EXTENSION IF NOT EXISTS vector, which needs a database role allowed to install extensions. Any other vector database can be registered with VectorStoreManager::extend():

use Prism\Memory\Facades\PrismMemory;

// In a service provider's boot(). $config is memory.drivers.qdrant, or [] when absent.
PrismMemory::stores()->extend('qdrant', fn (array $config, $app) => new QdrantVectorStore($config));

Set MEMORY_STORE=qdrant to use it. The factory must return an implementation of Prism\Memory\Contracts\VectorStore.

Remember and recall#

use Prism\Memory\Facades\PrismMemory;
use Prism\Prism\Facades\Prism;

$memory = PrismMemory::for($user, scope: 'support');

// The whole exchange, including tool steps. Returns the ids written.
$ids = $memory->remember($response->messages);

$recollection = $memory->recall('billing address', budget: 1500);

Prism::text()
    ->using('anthropic', 'claude-sonnet-4-5')
    ->withSystemPrompt($instructions)
    ->withSystemPrompt($recollection->asContext())
    ->withPrompt($question)
    ->asText();

import {
  InMemoryVectorStore,
  RecallSettings,
  Vector,
  Weighting,
  recall,
} from '@particle-academy/prism-memory';

// embedding and queryEmbedding are number[] from your embeddings provider.
const store = new InMemoryVectorStore();

await store.upsert([{
  id: 'm-1',
  collection: 'user:7',
  content: 'Billing address is 12 Harbour Road.',
  kind: 'observation',
  vector: Vector.of(embedding),
  embeddingModel: 'text-embedding-3-small',
  metadata: {},
  provenance: { source: 'support', author: 'user:7', observedAt: 1_789_000_000 },
  createdAt: 1_789_000_000,
}]);

const relevant = await recall(
  store,
  { collections: ['user:7'], vector: Vector.of(queryEmbedding) },
  new RecallSettings(5, 8, null, new Weighting(0.8, 0.2)),
);

for (const memory of relevant.memories) {
  console.log(memory.score, memory.record.content);
}

import time

from prism_memory import (
    InMemoryVectorStore,
    Provenance,
    RecallSettings,
    Vector,
    VectorRecord,
    Weighting,
    recall,
)

# embedding and query_embedding are lists of floats from your embeddings provider.
store = InMemoryVectorStore()
store.upsert([
    VectorRecord(
        id="m-1",
        collection="user:7",
        content="Billing address is 12 Harbour Road.",
        created_at=1_789_000_000,
        vector=Vector.of(embedding),
        embedding_model="text-embedding-3-small",
        provenance=Provenance(source="support", author="user:7", observed_at=1_789_000_000),
    )
])

relevant = recall(
    store,
    ["user:7"],
    Vector.of(query_embedding),
    RecallSettings(limit=5, weighting=Weighting(relevance=0.8, recency=0.2)),
    now=int(time.time()),
)

for memory in relevant.memories:
    print(memory.score, memory.record.content)

remember() (PHP)#

remember(iterable|Message|string $subject, array $metadata = [], ?Carbon $occurredAt = null): array

• Accepts a string, one Prism message, or a list of messages and strings. User and assistant messages are stored with their role; tool results are stored verbatim unless remember_tool_results is off; system messages are skipped. Any other value throws UnstorableMemory.
• $metadata is merged into every record. Values must be scalars or null, and keys cannot contain ->, [ or ". The keys kind, role and source_* are reserved.
• $occurredAt sets when the remembered thing happened (default now). Recency and forgetBefore() use this time.
• Ids are derived from the content, role and tool name, so remembering the same text twice replaces one record.

recall() (PHP)#

recall(
    string $query,
    ?int $limit = null,
    ?int $budget = null,
    ?Weighting $weighting = null,
    ?float $minScore = null,
    array $filter = [],
): Recollection

• budget fills up to that many estimated tokens instead of taking a fixed limit. Memories are taken best first; one that does not fit is skipped and smaller ones behind it can still be taken.
• weighting overrides the configured mix, for example new Weighting(relevance: 0.7, recency: 0.3), Weighting::balanced() or Weighting::relevanceOnly().
• filter is equality on metadata; an array value means "any of". For example filter: ['kind' => 'tool_result'].
• An empty query returns an empty Recollection.

TypeScript and Python have no token budget: RecallSettings sets limit, overfetch, minScore and the Weighting, and recall() returns at most limit results. Filters and a store-side minimum similarity are passed with the query (filter, minSimilarity in TypeScript; filter=, min_similarity= in Python).

Embedding runs on the queue (PHP)#

remember() writes the records immediately and dispatches an EmbedMemories job to embed them. A record cannot be recalled until its vector exists. On Laravel's default sync queue connection the job runs inline, so this is invisible. With a queue worker, a recall() straight after remember() does not find the new records until the queue has processed the job.

// Embed inline for a caller that must read its own write.
$memory->synchronously()->remember('Prefers email over phone.');

$memory->pending();      // stored but not yet searchable
$memory->embedPending(); // embed one batch of whatever is waiting

synchronously() returns a copy, so it does not change the shared instance. A pending() count that stays above zero means the queue is not draining.

Forgetting#

$memory->forget($ids);         // only these memories
$memory->forget();             // EVERY memory for this owner and scope
$memory->forgetBefore($date);  // everything that occurred before $date
$memory->count();

await store.forget('user:7', ['m-1']);
await store.purge('user:7');
await store.purgeObservedBefore('user:7', 1_789_000_000);
await store.count('user:7');

store.forget("user:7", ["m-1"])
store.purge("user:7")
store.purge_observed_before("user:7", 1_789_000_000)
store.count("user:7")

Deletes are hard deletes, and each call returns the number of rows removed. forgetBefore() cuts on when the remembered thing occurred, not on when the row was written.

Data shapes#

PHP: Recollection#

recall() returns a Recollection, which is countable and iterable over Recalled items.

The prompt helpers are chronological so the recalled block stays byte-stable between turns and provider prompt caches keep hitting.

Each Recalled has id, content, kind (MemoryKind::Observation or MemoryKind::ToolResult), role, similarity (raw cosine), recency (decay factor 0 to 1), score (what the ranking used), occurredAt and metadata.

TypeScript and Python#

Recency is measured from provenance.observedAt when set, otherwise from createdAt. Vectors serialise with toStorage() / to_storage() as base64 of little-endian float64 values, the same format PHP stores.

Stores#

InMemoryVectorStore keeps records in process memory. It reports itself as volatile and loses everything when the process exits; use it for tests and single-process tools. For durable storage, implement the VectorStore contract:

TypeScript methods return promises, except durability(). A search must skip records with no vector and must refuse to mix vectors from different embedding models in one collection.

With Harness (PHP)#

Prism Memory can act as Harness's eviction sink and context recall. Turns that compaction pushes out of the context window are stored in memory, and the agent gets a recall_context tool that searches them by meaning within the token budget Harness passes.

use Prism\Harness\Contracts\ContextRecall;
use Prism\Harness\Contracts\EvictionSink;
use Prism\Memory\Harness\MemoryContextRecall;
use Prism\Memory\Harness\MemoryEvictionSink;
use Prism\Memory\PrismMemory;

// In a service provider. Both packages installed.
$this->app->singleton(EvictionSink::class, fn () => new MemoryEvictionSink(
    app(PrismMemory::class),
    $owner,
));

$this->app->singleton(ContextRecall::class, fn () => new MemoryContextRecall(
    app(PrismMemory::class),
    $owner,
));

$owner is who the memories are filed under, usually the participant whose conversation it is. The scope is the Harness thread key. Evicted turns are stored with the metadata evicted => true; pass evictedOnly: true to MemoryContextRecall to search only those. A message that cannot be stored is reported and skipped without dropping the rest of the turn.

Harness is optional: nothing in Prism Memory loads these classes unless you bind them.

Errors#

PHP throws a dedicated exception class. TypeScript and Python throw MemoryError with a code; the codes are in the TypeScript MemoryErrorCode type and the Python ErrorCode enum.

Security notes#

• Memory is addressed by owner and scope. Recall in one scope never returns another scope's memories, so keep unrelated conversations in separate scopes.

• Recalled text is what users and tools said earlier. Treat it as untrusted input in the prompt, the same as the original messages.

• Tool results are stored verbatim by default, including any personal data they contain. Turn off remember_tool_results where tool output is disposable, and set retention if records must expire.

• Deletes are hard deletes and return a count, so an erasure request can be evidenced.

• Source