Skip to content

Memory System

The memory system is the core persistence layer of Signet. Memories are stored in a SQLite database at $SIGNET_WORKSPACE/data/signet.db. Every memory is synchronized with the full-text search index (FTS5), carries a SHA-256 content hash for deduplication, and participates in a versioned audit trail. A vector embedding is written when an embedding provider succeeds, but memories can exist without one. The Daemon owns all writes. Direct database modification is unsupported.

The path from input to stored memory follows four phases: ingestion, pipeline processing, indexing, and search.

When a client POSTs to POST /api/memory/remember, the daemon immediately writes the memory row to SQLite. The FTS5 index is updated synchronously. The request then makes a best-effort embedding attempt and persists the vector if the provider succeeds. The write succeeds even if the embedding provider is unavailable — those memories remain searchable by keyword only.

The saved row is episodic evidence. Its content and type are immutable once written as episodic evidence, while metadata can still be curated through the mutation API. Dreaming later selects it with related artifacts, transcripts, and summaries, then may derive audited semantic claims or links without rewriting the original evidence. No extraction job is created by the write path.

Search (POST /api/memory/recall) runs hybrid BM25 + vector search, optionally augmented by the knowledge graph, and returns a scored, ranked list. This is the current retrieval substrate. Its job is to produce a useful candidate set for context construction, not merely to act as a better search engine in isolation.

Pipeline V2 is the autonomous memory processing subsystem. It runs source ingestion, retention, summaries, and Dreaming under memory.pipelineV2 (see Configuration). A remember save is immediately available as immutable episodic evidence; it does not start a per-memory extraction or decision worker.

Direct LLM fact/entity extraction from raw memory content was retired under the Dreaming cutover (#946). platform/daemon/src/pipeline/extraction.ts now holds only shared JSON recovery and parsing helpers consumed across the pipeline (reranker, contradiction, dreaming) and by the ontology modules. Semantic graph authorship flows through the audited Dreaming apply path, not a per-memory extraction stage.

Dreaming reads the agent-scoped episodic aggregation surface: user evidence, source artifacts, live transcripts, and temporal summaries. Each source is preserved with its provenance. When a session artifact has a matching transcript or temporal-DAG node, Dreaming uses that canonical node once rather than repeating the same content from every storage representation. The immutable artifact remains available for lineage and recovery.

Dreaming is the only automatic semantic writer. It reasons over the selected evidence and submits audited ontology operations through the daemon-owned apply path. Pause/frozen controls can prevent mutation, but there is no parallel extraction, decision, or structural worker that writes semantic state.

Recall is implemented in platform/daemon/src/memory-search.ts by hybridRecall. Its job is not to find one perfect row. Its job is to collect a broad candidate set, filter it to the caller’s allowed view, shape the evidence, and return a bounded list of useful context.

The route layer checks the caller has recall permission. The search layer then enforces the data boundary again with one shared filter:

  • agentId and readPolicy control agent visibility. If agentId is present and readPolicy is omitted, recall defaults to isolated access.
  • project restricts results to that project.
  • scope restricts results to that explicit scope. When scope is omitted, normal recall excludes scoped memories.
  • type, tags, who, pinned, importance_min, since, and until narrow the memory rows inside that visibility boundary.

The important safety rule is:

Candidate IDs may be broad, but memory content is not loaded, reranked, summarized, dampened, expanded, or access-tracked until the shared filter has authorized those IDs.

That rule matters because vector search and graph traversal are intentionally high-recall channels. They can produce IDs that did not pass through the FTS SQL filter. hybridRecall therefore runs an explicit authorize_candidates stage before any content-bearing stage.

Recall starts with the original query, an optional keywordQuery, and a normalized limit. limit is clamped to a bounded range so callers cannot force unbounded recall work.

The keyword side uses sanitizeFtsQuery to produce a safe FTS5 MATCH expression. If sanitization leaves no searchable tokens, the FTS and hint paths are skipped instead of issuing an empty MATCH.

expandRecallKeywordQuery adds a small mechanical expansion set for known class-to-instance gaps. The expansion affects keyword and hint search only. Vector search and model summaries still use the user’s original query.

Candidate collection uses several independent channels:

  • Memory FTS queries memories_fts, joins to memories, applies the shared filter, and normalizes BM25 scores within the batch.
  • Prospective hints query memory_hints_fts. Hints are write-time alternate phrasings. They can rescue a memory whose content does not use the same words as the current query.
  • Vector search embeds the original query and searches vec_embeddings through sqlite-vec. When that extension is unavailable, it uses a bounded cosine scan over the newest canonical vectors instead. The fallback is an explicitly partial recent-window channel: responses expose meta.vectorCompleteness: "recent-window" and meta.searchedWindow (the default is 10,000 rows), so it must not be read as complete workspace recall. Vector search cannot pre-filter every recall scope, so constrained searches over-fetch and rely on authorization after merge.
  • Structured path candidates search entity/aspect/group/claim paths so structured knowledge can surface even when its prose is sparse.
  • Graph traversal resolves focal entities and walks the knowledge graph. In traversal-primary mode, graph results are treated as a first-class retrieval channel rather than a small boost.

Flat lexical, hint, vector, and structured scores are merged by memory ID. Keyword and vector hits are fused by rank, not by raw score: each list is ordered after the min_score cut, each hit adds 1 / (60 + position) for every list it appears in, and the sum is scaled by 61 / 2. A hit first in both lists scores 1, a hit first in only one list scores 0.5, a hit in both lists outranks a hit at the same position in one list, and BM25 and cosine magnitudes never compete on one scale. Hint, structured, and temporal evidence then replace a fused score only when they are stronger.

Pure hint-only hits are capped at 0.75. Because a hit found by keyword or vector search alone scores at most 0.5, a hint-only hit can outrank it; only hits found by both lists can score above the cap. Hints are generated alternate phrasings, so this lets them rescue a memory whose words differ from the query.

In traversal-primary mode, the merged order fills a bounded candidate budget. A quarter of that budget is reserved for the top vector hits, so a long keyword list or graph walk cannot crowd out the best semantic matches before reranking.

Traversal-primary mode sorts traversal candidates before selection and max-merges traversal overlap with flat candidates. This prevents a weak graph score from discarding stronger direct evidence for the same memory.

After candidate collection and coarse score fusion, authorize_candidates requeries memories with the shared filter and removes anything outside the caller’s allowed view. This is the boundary between “IDs only” and “content can now be read.”

New recall stages should follow this rule:

  • Stages that only produce IDs and scores may run before authorization.
  • Stages that read memory content, send text to a model, build summaries, inspect entity coverage, or update metadata must run after authorization.

Once candidates are authorized, recall can safely use content-bearing post-processing:

  • Structured Evidence Convolution (SEC-lite) compares lexical, semantic, hint, traversal, and structured signals so graph-only results do not blindly dominate direct evidence. It reorders admitted candidates; only candidates without lexical or semantic evidence can fall below min_score here.

  • Facet coverage can read candidate content and prefer rows that cover more of the query’s facets.

  • Rehearsal boost applies a small access-frequency and recency signal when enabled.

  • Reranking reads the query against each of the authorized top-N candidates (memory.pipelineV2.reranker.topN, default 20) with a local cross-encoder (reranker.crossEncoderModel, default mixedbread-ai/mxbai-rerank-xsmall-v1, about 90 MB, downloaded on first use), and fuses its order with the retrieval order by reciprocal rank so it can lift a relevant memory that shares no words with the question without overturning order retrieval already got right. It runs in its own worker thread, one rerank at a time. On CPU it scores each query and memory pair separately and stops between pairs once the deadline has passed, so a slow rerank gives up quickly instead of holding the worker for the next recall. The compiled binary runs it on WebAssembly by default, where 20 candidates can take longer than the deadline on a busy machine; set reranker.device: cpu with reranker.onnxRuntimePath to run it on the native ONNX runtime instead (several times faster). The model loads in the background on first use; while it is loading, busy, or slower than three quarters of reranker.timeoutMs, recall falls back to an embedding blend for that request. meta.reranker reports which reranker ran (cross-encoder, embedding, llm, or none), the device it ran on, and why a fallback happened. Set crossEncoderModel: "" to use the embedding blend only, or useExtractionModel: true for the LLM reranker.

  • Acceleration (optional). signet accelerate installs and configures a faster runtime, then signet restart applies it and signet accelerate verify checks it:

    • signet accelerate cpu downloads the native ONNX runtime for this platform (about 35 MB, checked against a pinned sha512) and uses it for embeddings and the cross-encoder.
    • signet accelerate cuda (Linux x64, NVIDIA driver 525 or newer) also installs the ONNX Runtime CUDA provider and the CUDA 12 libraries it links against, including all cuDNN 9 sub-libraries (about 2.9 GB installed, fetched member by member from NuGet and PyPI and checked against pinned SHA-256 hashes), and runs the cross-encoder on the GPU in full precision.
    • signet accelerate metal (Apple silicon Macs) runs the cross-encoder on the GPU through Metal in full precision. It installs nothing beyond the native ONNX runtime above, whose macOS build already contains the Metal-backed GPU provider. Candidates of similar length share one GPU run, which is where it gains over the CPU: on an Apple M6, the rerank stage for 10 short memories took 24 to 37 ms against 79 to 150 ms on the native CPU runtime, while candidates of several hundred tokens each run at about CPU speed. Embeddings use the native CPU runtime, as with cpu.
    • signet accelerate off returns to WebAssembly; signet accelerate alone shows the detected GPU and the active runtimes. CPU-runtime status verifies pinned hashes. CUDA status checks that every pinned provider and library file has its expected size; installation verifies their hashes.

    Enabling or disabling acceleration preserves hand-set onnxRuntimePath values and CUDA library directories; only paths inside the managed accelerators directory are replaced or removed. A custom runtime must meet the version and CUDA requirements below. Config edits preserve symlinks, permission bits, comments, and unrelated keys, and save the previous content beside the resolved target as .bak. Concurrent edits fail rather than silently overwrite each other. An interrupted edit can leave a .lock file; confirm no config editor is running before removing it and retrying.

    Verification waits at most --timeout seconds for a cross-encoder result (default 120, minimum 5). An empty recall stops immediately as “not verified”: add a matching memory and retry; it is not proof of runtime failure or success.

    Native embeddings produce slightly different vectors from WebAssembly, so switching re-embeds stored memories in the background; recall keeps using the current vectors until the new index is ready. The active generation retains its ONNX package path when the configuration removes it during a switch back to WebAssembly. An explicit configured package path still takes precedence, allowing the same runtime to be relocated without re-embedding. Files live in runtime/accelerators inside the Signet workspace. The command writes these keys, which can also be set by hand:

    embedding:
    runtime: onnxruntime
    onnxRuntimePath: /path/to/onnxruntime-node
    memory:
    pipelineV2:
    reranker:
    device: cuda # or cpu, or metal on Apple silicon
    onnxRuntimePath: /path/to/onnxruntime-node
    cudaLibraryPaths:
    - /path/to/cuda12/lib

    onnxRuntimePath is an onnxruntime-node package directory (with its CUDA provider for device: cuda) at the version the Signet build reports; the compiled binary refuses a different version. cudaLibraryPaths lists directories of CUDA 12 shared libraries to load before the CUDA provider, so no system-wide CUDA 12 install or LD_LIBRARY_PATH is needed. If the CUDA, Metal or native CPU worker cannot start, recall falls back to the default runtime and logs why. When the @signet/native addon is present, the cross-encoder tokenizes query and candidate pairs natively and caches each candidate’s tokens.

  • Transcript prefetch uses the owner’s maintenance priority, below primary memory queries. Placement shares the original 30-second transcript-read deadline, including queue time; a busy maintenance lane can therefore delay placement within that bound. A failed or expired read leaves the primary results available and marks transcript evidence failed. Independent row failures retain successful excerpts, mark evidence failed, and wait for all selected reads to settle before returning. Cancellation observed before finalization rejects recall instead of claiming results or updating access tracking. Before placement, the owner revalidates each cached excerpt’s scope and artifact revision. Deleted, purged, or changed artifacts are withheld.

  • Dampening penalizes low-overlap semantic hits, hub-like entity dominance, and other noisy retrieval shapes. The low-overlap penalty never drops a hit below the scores it leaves untouched, and an entity counts as a hub only when it is linked to at least a quarter of the agent’s memories, so the topics a user talks about most are not penalized for being central.

  • Currentness annotates superseded memories and boosts current replacements.

All of these stages are non-fatal. Recall should degrade toward simpler keyword/vector results rather than fail the whole response.

Hydration fetches full memory rows with the same shared filter used by authorization. Constrained searches use a larger pre-hydration window so valid later candidates can still return after broad vector or traversal IDs are removed.

Assembly walks the pre-hydrated scored list, keeps only hydrated rows, and then applies the caller’s limit. Access tracking updates only the memory IDs that actually appear in the returned primary result set. Synthetic cards and unauthorized candidates never update access_count.

Supplementary results may include:

  • source-backed Obsidian chunks,
  • native memory artifacts,
  • an LLM summary card when the LLM reranker path has remaining timeout budget,
  • linked rationale memories for decision results,
  • constructed graph context cards.

The final response is capped to limit. Supplementary rows are marked with supplementary: true so callers can distinguish them from ordinary memory rows.

If normal memory candidates produce no hits, recall can fall back to source chunks and native memory artifacts. These paths return synthetic recall rows rather than materializing new memories records, but each fallback is only enabled when its backing rows can satisfy the caller’s scope boundary.

Source chunk vector fallback is disabled for project-scoped recall until chunk embeddings carry a strong source root/project binding. Project-scoped searches still use authorized memory rows and native source artifacts; they do not guess source ownership from chunk text metadata.

Memory-only filters (type, tags, who, pinned, importance_min, scope) disable the source rescue paths, because source rows cannot satisfy them. Date bounds (since, until) do not: native memory artifacts are filtered by their file modification time, which is also the created_at they report. Source chunk vector fallback is skipped under date bounds, because a chunk’s time is when it was embedded, not when its content was written.

Recall also returns a bounded amount of transcript evidence. After the memory results are ranked, keyword search over the requesting agent’s own captured session transcripts adds at most search.transcript_evidence_limit excerpts (default 2, maximum 5, 0 disables). Keyword search proposes up to twice that many candidates; when the cross-encoder reranker is configured, the candidates and the bottom results they would replace are scored together and the most relevant fill those slots, so an excerpt displaces a memory only when it is judged more relevant. Without the cross-encoder, or when it is busy or still loading, the top keyword candidates take the bottom slots. Either way the result count stays within limit. An excerpt is the best-matching window of about 900 characters with credentials redacted, has source: "transcript", type: "transcript", supplementary: true, an id of the form transcript:<session>, and the session in session_id. Sessions already represented in the results are skipped. Transcripts are never read across agents, whatever the read policy, and the lane is skipped for temporal windows and memory-only filters (type, tags, who, pinned, importance_min, scope), which transcripts cannot satisfy. Date bounds (since, until) apply to the excerpt’s created_at, which is the session start when known and otherwise the capture time. This keeps details Dreaming does not file, such as general information the assistant gave, reachable without filing them as claims. Prompt-submit injection does not include transcripts. Full transcript search remains available through /api/sessions/search, MCP session_search, and signet session search.

Every major stage records timing data in meta.timings. Slow recalls log a stage breakdown so latency regressions can be localized without guessing.

Secondary channels are deliberately best-effort. Embedding, vector search, graph traversal, structured evidence, reranking, dampening, freshness-aware rehearsal, currentness, source fallback, and LLM summary failures are logged and skipped. The caller should receive the best safe recall response the daemon can produce from the remaining channels.

Terminal window
curl -X POST http://localhost:3850/api/memory/recall \
-H 'Content-Type: application/json' \
-d '{
"query": "database preferences",
"limit": 10,
"type": "preference",
"importance_min": 0.5
}'

Optional filters: type, tags, who, pinned, importance_min, since, until, agentId, readPolicy, policyGroup, project, and scope.

Before any memory is written, content passes through normalization (platform/daemon/src/content-normalization.ts).

Storage content trims whitespace and collapses internal whitespace runs to single spaces. Normalized content additionally lowercases the result and strips trailing punctuation. The SHA-256 hash is computed over normalized content (or over lowercased storage content if normalization produces an empty string).

storageContent = trim + collapse whitespace
normalizedContent = storageContent.toLowerCase().replace(/[.,!?;:]+$/, "")
hashBasis = normalizedContent || storageContent.toLowerCase()
contentHash = sha256(hashBasis)

The content_hash column has a unique constraint. If a write produces a hash that already exists as a non-deleted memory, the write is skipped and the existing memory ID is returned. This deduplication fires both on explicit remember calls and on pipeline V2 add proposals.

During controlled-write processing, update and delete proposals are evaluated for contradiction risk (platform/daemon/src/pipeline/worker.ts).

The detector tokenizes both the new fact and the target memory content (lowercase, punctuation stripped, minimum 2-char tokens). A contradiction is flagged when all three conditions hold:

  1. Lexical overlap between the two texts is at least 2 tokens (they are about the same subject).
  2. One text contains a negation token (not, no, never, cannot, dont, wont, etc.) and the other does not.
  3. Or, the texts contain antonym tokens in opposing positions (e.g., one has enabled and the other has disabled).

Registered antonym pairs: enabled/disabled, allow/deny, accept/reject, always/never, on/off, true/false.

Proposals that trigger contradiction detection are flagged with contradictionRisk: true and reviewNeeded: true in the audit record. The proposal is still blocked (UPDATE/DELETE are not yet applied autonomously), but the flag makes it inspectable.

POST /api/memory/modify accepts a batch of patch objects. Each patch targets one memory by ID and can update content, type, importance, tags, pinned, or who. A reason string is required for every patch (either per-patch or as a request-level default).

Content changes trigger re-embedding synchronously before the database write. The new embedding replaces the old one in the embeddings table. Each patch accepts an optional if_version integer for optimistic concurrency control — if the memory’s current version does not match, the patch returns version_conflict without writing.

The batch limit is enforced server-side. Results are returned per patch, including status, currentVersion, newVersion, contentChanged, embedded, and duplicateMemoryId if a content change would have produced a hash collision.

Terminal window
curl -X POST http://localhost:3850/api/memory/modify \
-H 'Content-Type: application/json' \
-d '{
"reason": "corrected preference",
"patches": [
{
"id": "<memory-id>",
"content": "User prefers spaces over tabs",
"if_version": 3
}
]
}'

Every successful modify writes a modified event to memory_history with the previous content, new content, actor, reason, and timestamp.

POST /api/memory/forget operates in two modes: preview and execute.

In preview mode, the endpoint evaluates candidates (by query, IDs, or filter fields: type, tags, who, source_type, since, until) and returns a candidate list with a confirmToken. No writes occur. For batches exceeding the confirmation threshold, the confirmToken must be echoed back in the execute call.

In execute mode, each candidate is soft-deleted: is_deleted = 1 and deleted_at are set. The reason field is required. Passing force: true permits soft-deleting pinned memories; it does not hard-delete the row immediately. Batch if_version is not supported — use DELETE /api/memory/:id for version-guarded single deletes.

Terminal window
# Preview
curl -X POST http://localhost:3850/api/memory/forget \
-H 'Content-Type: application/json' \
-d '{"query": "old project notes", "mode": "preview"}'
# Execute
curl -X POST http://localhost:3850/api/memory/forget \
-H 'Content-Type: application/json' \
-d '{
"query": "old project notes",
"mode": "execute",
"reason": "project is archived",
"confirm_token": "<token-from-preview>"
}'

Every forget writes a deleted event to memory_history.

Soft-deletion sets is_deleted = 1 and records a deleted_at timestamp. Soft-deleted memories are excluded from all search results and API list endpoints. They remain in the database as tombstones for the retention window (default: 30 days).

Within the retention window, a memory can be recovered:

Terminal window
POST /api/memory/:id/recover
{ "reason": "accidentally deleted" }

Recovery clears is_deleted and deleted_at, increments the version, and writes a recovered event to memory_history. The endpoint returns the current and new version numbers.

Recovery fails with a 409 if the memory is not deleted (not_deleted), if the retention window has expired (retention_expired), or if an if_version check fails (version_conflict). It returns 503 if mutationsFrozen is active.

After the retention window elapses, the retention worker archives the memory to memories_cold, removes its graph links and embeddings, and hard-deletes the tombstone. Recovery is no longer possible after that point.

Every mutation to a memory row is recorded in the memory_history table. This provides a complete, ordered audit trail for each memory.

Field Description
id UUID for the history event
memory_id The memory this event belongs to
event Event type: created, modified, deleted, recovered, none
old_content Content before the change (null for creates)
new_content Content after the change (null for deletes)
changed_by Actor string (harness name, pipeline-v2, pipeline-shadow)
reason Required human-readable reason for the change
metadata JSON blob with additional context (pipeline details, flags)
created_at ISO timestamp of the event

Pipeline V2 records history for every proposal evaluated, including those that were skipped, blocked, or deduplicated. Shadow mode proposals use changed_by = 'pipeline-shadow' and event = 'none' to distinguish them from real mutations. The metadata field carries pipeline-specific fields: shadow, proposedAction, targetMemoryId, confidence, contradictionRisk, reviewNeeded, blockedReason, and the source fact details.

History events are retained for 180 days by default, then purged by the retention worker.

Every memory has an importance score between 0.0 and 1.0. Recall applies an age-based score to non-pinned memories using days since creation:

effective_score = importance × 0.95 ^ age_days

The 0.95 factor is currently built into the recall/classification code and is not loaded from memory.decay_rate in agent.yaml. last_accessed and access_count are used separately for rehearsal and access-frequency boosts. Pinned memories always receive a non-decaying score of 1.0. The critical: prefix also sets their stored importance to 1.0; an API pinned: true request pins the memory but does not itself rewrite the importance field.

The retention worker (platform/daemon/src/pipeline/retention-worker.ts) runs every 6 hours and purges expired data in a strict sequence. The dependent graph-link, embedding, and tombstone steps run in one write transaction so a vector cleanup failure cannot commit only part of the purge. History and job cleanup run in separate transactions.

The purge order is mandatory — later steps depend on earlier ones having removed their referencing rows first:

  1. Graph links (memory_entity_mentions) for tombstoned memories past the retention window. Entity mention counts are decremented; entities themselves are kept, even at zero mentions.
  2. Embeddings for the same tombstoned memories (from the embeddings table).
  3. Tombstones — the memories are copied to memories_cold, then the memories rows themselves are hard-deleted. The memories_ad trigger handles FTS5 cleanup automatically.
  4. History events older than the history retention window.
  5. Completed jobs older than the completed job retention window.
  6. Dead-letter jobs older than the dead job retention window.

Each step is capped at batchLimit rows per sweep (default: 500) to bound write latency.

Default retention windows:

Data Retention
Soft-deleted memories (tombstones) 30 days
History events 180 days
Completed pipeline jobs 14 days
Dead-letter pipeline jobs 30 days

These are currently built-in worker defaults rather than agent.yaml settings.

Pipeline V2 processing is driven by a persistent job queue in the memory_jobs table. Jobs are atomic — lease acquisition and status updates happen inside write transactions.

pending → leased → completed
→ failed → pending (retry)
→ dead (max attempts exceeded)

When a job fails, it returns to pending status for retry unless attempts >= max_attempts, in which case it moves to dead. Dead jobs are retained for the dead-letter window (default: 30 days) and then purged.

The worker polls for pending jobs by selecting the oldest pending row with attempts < max_attempts. It atomically sets status = 'leased' and increments attempts in the same write transaction. This prevents two workers from processing the same job.

A stale lease reaper runs every 60 seconds. Jobs that have been leased for longer than leaseTimeoutMs (configurable) are reset to pending for pickup by the next poll cycle.

On consecutive failures, the worker applies exponential backoff:

delay = min(BASE_DELAY × 2^failures, MAX_DELAY) + random_jitter

BASE_DELAY is 1000ms, MAX_DELAY is 30,000ms, jitter up to 500ms. Successful jobs reset the failure counter.

The legacy extraction queue is retired. Dreaming selects new evidence directly. At startup, each live historical extraction source is promoted to the durable episodic cursor before its obsolete job is terminalized.

Every semantic memory has a type field that classifies its role. Dreaming derives those rows from episodic evidence; the original evidence remains immutable and provenance-bearing.

Type Meaning Example
fact Objective, verifiable information “Signet stores data in SQLite”
preference User or agent preferences and inclinations “User prefers dark mode”
decision Choices made, options selected or rejected “Decided to use PostgreSQL”
rule Constraints or standing instructions “Never expose tokens”
learning Newly learned information or patterns “Discovered a faster workflow”
issue A known problem or failure “The auth flow is broken”
procedural How-to knowledge, steps, workflows “Run bun install before building”
semantic Concepts, definitions, and relationships “BM25 is a term-frequency ranking function”

An explicit save stores the type given in the request (see POST /api/memory/remember). When the request gives no type, the daemon infers one with keyword matching:

  • preference — triggers on: prefers, likes, wants
  • decision — triggers on: decided, agreed, will use
  • rule — triggers on: never, always, must
  • learning — triggers on: learned, discovered
  • issue — triggers on: bug, broken, problem
  • fact — default when no pattern matches

importance is a float from 0.0 to 1.0 set at creation time. The pipeline uses fact.confidence as the importance for autonomously created memories. Explicit saves default to 0.8.

tags are stored as comma-separated text and support filtering at recall time. The API accepts either a comma-separated string or a string array. The critical: prefix sets pinned = 1 and importance = 1.0. The [tag1,tag2]: prefix sets tags directly.

Both can be combined: critical: [project,auth]: never expose tokens.

Endpoint Method Description
/api/memory/remember POST Save a memory
/api/memory/recall POST Hybrid search
/api/memories GET List memories (paginated)
/api/memory/:id GET Fetch one memory by ID
/api/memory/:id PATCH Update fields on one memory
/api/memory/:id DELETE Soft-delete one memory (version-guarded)
/api/memory/:id/recover POST Recover a soft-deleted memory
/api/memory/modify POST Batch patch memories
/api/memory/forget POST Batch soft-delete with preview/execute mode
/api/memory/search GET Hybrid recall alias
/api/memories/:id/tombstone POST Force-soft-delete one memory
/api/memories/:id/supersede POST Mark one memory superseded by another
/memory/search GET FTS and filter search
/memory/similar GET Vector similarity search
/api/embeddings GET Export embeddings

See Api for full request/response schemas.