Memory (memory)

Category: data | Form: | Symbol: Me

Durable agent memory — learned facts, preferences, and context that survive across conversations

Long-term memory store for agents. Bond one to a triformer (subconscious.memory.element) and its subconscious automatically stores, updates, and forgets memories; recall blends content, conversation-context, and intention similarity. Supports per-person scoping (subject_scoping) so facts about one person never surface for another, and configurable conscious access so the agent itself can search or manage its own memory as tools. Two agents bonded to the same Memory share knowledge.

Relationships

• Attaches to: rate-limit, auth-policy

Capabilities

• durable-memory: Cross-session memory storage with categories (fact, preference, procedure, context, correction) and automatic eviction at capacity
• blended-association-recall: Recall scored across three lanes — content similarity, conversation-context similarity, and intention similarity — with element-configured weights
• subject-scoping: Per-person memory partitioning: memories about one interlocutor (circle member, entity, or guest) never surface for another; includes forget_subject right-to-be-forgotten
• conscious-access: Configurable exposure of memory ops as agent tools (none / read / read_write) — the involuntary-subconscious default can be selectively relaxed
• shared-memory: Multiple agents bonding the same element share its memories — team knowledge without a separate mechanism
• retention: Optional per-category TTL reaping

Properties

Property	Type	Default	Description
description	string	—	Human-readable description of what this memory store is for
scope	string	"private"	Declared sharing intent. private — one agent’s own memory; shared — deliberately bonded by multiple agents (team knowledge). Documentation of intent for the panel and audits; the enforcement mechanism is which agents hold a bond to this element.
subject_scoping	boolean	false	When true, memories are partitioned by WHO they are about: writes classify each memory as person-scoped (subject = the current interlocutor) or general (no subject), and recall only surfaces general memories plus those about the person currently speaking. When false, the subject columns are still populated when known but recall ignores them (everything is general).
conscious_access	string	"none"	Whether the bonded agent’s conscious mind gets memory tools. none — memory is fully involuntary (subconscious-managed only, the platform default stance). read — the agent gets memory_search / recall tools. read_write — the agent may also consciously store, update, and delete memories. Conscious writes flow through the same pipeline as subconscious ones (same embedding, categories, association capture, caps).
max_memories	integer	1000	Maximum stored memories in this element. At the cap, storing a new memory evicts the least-accessed, oldest memory. Enforced by the executor at store time.
max_per_subject	integer	200	Per-subject cap when subject_scoping is on — one chatty interlocutor cannot evict another person’s memories or the general pool. Eviction within the subject’s own rows only.
relevance_threshold	number	0.4	Minimum blended similarity score for recall (0 = return everything, 1 = exact match only). Enforced by the executor’s search — replaces the legacy hardcoded MIN_VECTOR_SCORE.
association_weights	object	—	Blend weights for the three association lanes at recall time. score = content·sim(query, memory content) + context·sim(current conversation window, memory’s stored context) + intention·sim(current turn goal, memory’s stored intention). Context and intention are captured at STORE time, so a memory can be found by the situation it was formed in even when its text shares nothing with the query. Weights are normalized if they don’t sum to 1.
retention	object	—	Optional per-category TTL (days). Memories older than the TTL are removed by the maintenance reaper (stats op / background sweep). Categories without an entry never expire. Sensible use: let context decay while fact/procedure persist.

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Post /ops/memories/{memory_id}/delete | Auth: Write

Delete a specific memory

Permanently removes one memory. Administrative or subconscious-evaluator action; with conscious_access read_write the agent itself may call it.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

forget_subject

Post /ops/forget_subject | Auth: Write

Delete ALL memories about a subject (right-to-be-forgotten)

Permanently deletes every memory whose subject matches — the right-to-be-forgotten surface. Destructive and irreversible; requires the X-Confirm: destructive header. General memories are untouched.

get

Get /ops/memories/{memory_id} | Auth: Read

Get a specific memory with metadata and association info

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

list

Get /ops/memories | Auth: Read

List memories with filters

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

schema

Get /ops/schema | Auth: Read

Get element input/output schema (MCP tools/list compatible)

Returns type-level port schemas from the TypeRegistry — not instance-specific overrides. Includes direction (input/output), required flag, and JSON schema per port. Useful for understanding what data an element accepts and produces.

search

Post /ops/search | Auth: Read

Blended-association memory recall (content + context + intention similarity)

Recall memories by meaning, situation, and purpose. The query text is embedded and scored against each memory’s content vector, plus (when provided) the current conversation window against stored context vectors and the current goal against stored intention vectors — weights come from this element’s association_weights. When subject_scoping is on, results are general memories plus those about the given subject only. Results below relevance_threshold are dropped.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_diff3

Get /ops/source/diff3 | Auth: Read

Preview a three-way merge of two commits without writing

Read-only. Computes what a merge of theirs (default: your base_commit) into ours (default: the draft tip) would produce: per-file conflicts with ours/theirs/base content, plus clean/fast_forward flags. Use after a 409 to see exactly what moved before re-splicing your change. GET /api/{element_path}/ops/source/diff3?theirs={sha}.

source_fixtures

Post /ops/source/fixtures | Auth: Write

Dry-run or apply approved Source seed fixtures

Scans .triform/fixtures/ manifests from the addressed data element Source repo. Defaults to dry_run=true and never imports live runtime data. Apply requires dry_run=false plus confirm=true and dispatches approved records through existing generated element ops.

source_merge

Post /ops/source/merge | Auth: Write

Three-way merge a commit into the draft branch

Merges theirs (default: your base_commit) into the draft branch. Clean (non-overlapping edits) → commits and advances draft, returns merged: true + the new commit. Conflicts → writes nothing and returns the conflict set to resolve and retry. Refused inside an active version-set scope (use version_sets_merge). POST /api/{element_path}/ops/source/merge {“theirs”: “{sha}”}.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Memory store statistics and maintenance

Returns counts by category and subject plus capacity info. Also runs the retention reaper: memories older than their category’s configured TTL are removed and reported in expired.

store

Post /ops/store | Auth: Write

Store a new memory

Stores a durable memory with content, category, and optional subject (who it is about) and association texts (the situation and goal it was formed in — embedded and stored for associative recall). At max_memories the least-accessed oldest memory is evicted; with subject_scoping on, per-subject eviction respects max_per_subject. Normally called by the agent’s subconscious evaluator; direct calls are for pipelines/automations and conscious read_write agents.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Post /ops/memories/{memory_id}/update | Auth: Write

Update a memory’s content (re-embeds)

Replaces the memory’s content and recomputes its content embedding. Category, subject, and association vectors are preserved unless explicitly changed. Used by the subconscious evaluator when new information supersedes an existing memory.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
MEMORY_NOT_FOUND	not_found	no	memory_id does not exist in this element
MEMORY_INVALID_CATEGORY	validation	no	category is not one of fact, preference, procedure, context, correction
MEMORY_SUBJECT_INCOMPLETE	validation	no	subject_type and subject_id must be provided together
MEMORY_CONFIRM_REQUIRED	validation	no	forget_subject requires the X-Confirm: destructive header
MEMORY_EMBEDDING_FAILED	internal	yes	Embedding generation failed — memory stored without vectors, text-search fallback only (store) or ILIKE fallback used (search)
MEMORY_STORE_FAILED	internal	yes	Database write failed — transient backend error