Core Concepts
Memory Record Structure
This page is the field-by-field reference for the Memory row. Every column listed here exists on the underlying memory model. The columns are grouped by purpose so you can navigate by intent rather than alphabetically.
Identity columns
| Column | Type | Notes |
|---|---|---|
id | integer (PK, auto-inc) | Internal numeric id. Indexed. |
vector_id | varchar(64), unique | Identifier issued by the vector index. Nullable until the embedding lands. |
parent_id | integer, nullable | Self-FK for hierarchical memories (a summary points at its child rows). |
cluster_id | bigint, nullable, indexed | Persistent cluster assignment for the intelligence views. |
Scope columns
| Column | Type | Behaviour |
|---|---|---|
user_id | int, FK → users.id, CASCADE | Hard owner. Server-resolved. |
project_id | varchar(64), FK → projects.project_id, SET NULL | Nullable. Drops to null if the project is deleted. |
environment | varchar(20), default "production" | Constrained to development, staging, production. |
Content columns (encrypted at rest)
| Column | Type | Notes |
|---|---|---|
text | bytes (LargeBinary) | Stored as text_ciphertext. Authenticated-encryption ciphertext with a per-user key. |
summary | bytes, nullable | Stored as summary_ciphertext. Reserved for batch 5:1 summarization. |
Semantic columns
| Column | Type | Source |
|---|---|---|
extracted_type | varchar(32), nullable | LLM-assigned: preference, fact, intent, relationship. |
extracted_key | varchar(64), nullable | LLM-assigned category slug, e.g. food, occupation. |
content_type | varchar(32), nullable, indexed | Classifier output: report, pitch_deck, blog, technical, meeting, ... |
tags | array of strings, nullable | Lower-cased dedup of user tags + top-5 semantic topics. |
source | varchar(64), nullable, indexed | Origin label such as api, email, web. |
event_type | varchar(64), nullable, indexed | Trigger label that produced the row. |
metadata_json | JSON, nullable | User keys merged with system keys. See Metadata. |
Scoring columns
| Column | Type / range | Meaning |
|---|---|---|
importance | float, default 0.5, range 0..1 | User- or semantic-driven weight. |
importance_score | int, nullable, 0..100 | Deterministic post-commit score (no LLM). |
quality_score | float, nullable, 0..1 | Semantic engine quality. |
confidence_score | float, nullable, 0..1 | Combination of evidence, consistency, and freshness. |
freshness_score | float, nullable, 0..1 | Content-type-aware freshness. |
evidence_count | int, default 0 | Count of corroborating relationships. |
consistency_score | float, default 1.0 | Drops as contradictions are recorded. |
usage_count | int, default 0 | Recall frequency, used as a ranking signal. |
decay_score | float, default 1.0 | Decreases over time without recall. |
Lifecycle columns
| Column | Type / default | Role |
|---|---|---|
tier | varchar(16), default "hot" | Storage tier — see Memory Tiers. |
retention_status | varchar(32), default "active" | Lifecycle state — see Memory Lifecycle. |
expires_at | timestamp, nullable | Computed from ttl_minutes when supplied. |
archive_at | timestamp, nullable | When the policy moves the row to archived. |
retention_expires_at | timestamp, nullable | When the policy soft-deletes the row. |
hard_delete_at | timestamp, nullable | Soft-delete timestamp + 7-day grace. |
deleted_at | timestamp, nullable | Soft-delete marker. |
created_at | timestamp, default now() | Set on insert, never updated. |
updated_at | timestamp, default now() | Tracks lifecycle transitions. |
Hierarchy and aggregation columns
| Column | Type | Notes |
|---|---|---|
is_summary | bool, default false | Marks aggregated memories. |
summary_of | JSON array of int | Child memory ids represented by this summary. |
source_input_hash | varchar(64), nullable | SHA-256 of the sanitized input — used for write-time dedup. |
What the API actually returns
MemoryResponse exposes the decrypted text (renamed content in some shapes), the metadata bundle, scoring fields, lifecycle fields, tier, source, event_type, tags, extracted_type, extracted_key, and timestamps. Encryption columns and internal hashes (source_input_hash, ciphertext columns) are never returned.