Memory Type API Matrix

A per-type cheatsheet: for every memory type, where to read more, how to create it, query it, and the key fields it carries across all three surfaces. Each type name links to its concept, guide, or example page.

Surfaces (columns):

SDK: SmartMemory Python methods (see the SmartMemory API).
MCP: agent tools (see MCP Tools).
REST: HTTP routes. All REST paths below are under the /memory prefix (e.g. POST /decisions/create → POST /memory/decisions/create).

For the conceptual model of each type, see Memory Types.

Universal operations (any type)

These work on every memory type. The type is set by memory_type or auto-classified by ingest().

Operation	SDK	MCP	REST
Create (pipeline)	`ingest(text)`	`memory_ingest`	`POST /ingest`
Create (direct)	`add(MemoryItem(memory_type=…))`	`memory_add`	`POST /add`
Get by id	`get(id)`	`memory_get`	`GET /{item_id}`
Update	`update(id, …)`	`memory_update`	`PATCH /{item_id}`
Delete	`delete(id)`	`memory_delete`	`DELETE /{item_id}`
Search	`search(q, memory_type=…)`	`memory_search`	`POST /search`
Search by metadata	`search_by_metadata(k, v)`	`memory_search_by_metadata`	`GET /by-metadata`
List	`list()`	`memory_list`	`GET /list`

Knowledge layer

Captured through ingest() (auto-classified) or add(memory_type=…). Queried by search(memory_type=…). These types evolve into one another (see Memory Dynamics).

Type	Create (SDK · MCP · REST)	Query	Key fields / notes
`semantic`	`add("…", memory_type="semantic")` · `memory_add` · `POST /add`	`search(memory_type="semantic")`	Context-independent facts. Default classification.
`episodic`	`add(memory_type="episodic")` · `memory_add` · `POST /add`	`search(memory_type="episodic")`	Time-bound events, carries `valid_time`. Evolves → `semantic` / `zettel`.
`procedural`	`add(memory_type="procedural")` · `dev_record_pattern` · `POST /add`	`search(memory_type="procedural")`	How-to / step sequences.
`pending`	`add(memory_type="pending")` / `distill()` · `memory_distill` · `POST /add`	`search(memory_type="pending")`	Holding bucket, `ConsolidationRouter` routes at ingest.
`zettel`	`add(memory_type="zettel")` · `memory_add` · `POST /zettel/notes`	`search(memory_type="zettel")` + `zettel_backlinks` · `GET /zettel/{note_id}/backlinks`	Atomic notes, `[[wikilink]]` cross-refs, `zettel_tags`. Rich graph API under `/zettel/*`.

Expertise layer

What to do (and not do). Each has a Manager + Queries lifecycle (supersession, reinforcement, contradiction). Recalled as a typed dict via search(query, expertise=True). Overview: Expertise vs Knowledge.

The SDK capture wrappers return typed objects, not string IDs: add_decision(...) returns a Decision, add_constraint(...) returns a Constraint, and add_learning(...) returns a Learned.

Type	Create (SDK · MCP · REST)	Query	Lifecycle & key fields
`decision`	`add_decision(content, …)` returns `Decision` · `decision_create` · `POST /decisions/create`	`search(expertise=True)["decision"]` · `decision_search` / `decision_list` / `decision_get` · `GET /decisions`, `/decisions/search`, `/decisions/{id}`	`supersede` / `reinforce` / `contradict` / `retract` / `provenance` / `find_conflicts`. Fields: `content`, `rejected_alternatives`, `rationale`, `decision_type`, `status`, `decision_id`, `confidence`, `constraints`, `domain`. Walkthrough: decisions lifecycle.
`opinion`	`add_opinion(content, subject)` · (derived) `evolution_synthesize_opinions` · `POST /opinions/create`	`search(expertise=True)["opinion"]`	Reinforce via `evolution_reinforce_opinions` · `POST /evolution/reinforce/opinions`. Fields: `subject`, `confidence`.
`observation`	`add_observation(entity_id, fact_id, aspect)` · (derived) `evolution_synthesize_observations` · `POST /evolution/synthesize/observations`	`search(expertise=True)["observation"]`	Synthesized from scattered evidence. Fields: `entity_id`, `fact_id`, `aspect`.
`reasoning`	`add_reasoning(trace, source_item_id)` · `reasoning_extract_trace` · `POST /reasoning/traces/store`	`search(expertise=True)["reasoning"]` · `reasoning_query_traces` · `POST /reasoning/traces/query`, `GET /reasoning/traces/{trace_id}`	Premises → conclusion chains, validation, and supersession. Also `reasoning_challenge`, `reasoning_proof_tree`.
`constraint`	`add_constraint(content)` returns `Constraint` / `ingest_structured(schema="constraint")` · `memory_ingest_structured` · `POST /ingest/structured`	`search(expertise=True)["constraint"]`	Hard rule discovered or imposed. Fields include `constraint_id`, `domain`, and `source`.
`learned`	`add_learning(content)` returns `Learned` / `ingest_structured(schema="learned")` · `memory_ingest_structured` · `POST /ingest/structured`	`search(expertise=True)["learned"]`	A lesson learned the hard way. Fields include `learned_id`, `lesson`, and `context`.

Operational types

Type	Create (SDK · MCP · REST)	Query / read	Lifecycle & key fields
`plan`	(PlanManager) / `ingest_structured(schema="plan")` · `memory_plan_create` · `POST /plans/create`	`memory_plan_get` / `memory_plan_active` · `GET /plans/{id}`, `/plans/active/list`	Update task: `memory_plan_update_task` · `PATCH /plans/{id}/task`, `complete` / `fail`. Fields: `title`, `tasks[]`, `status`, `context`.
`plan_task`	`ingest_structured(schema="plan_task")` · `memory_ingest_structured` · `POST /ingest/structured`	via parent plan (`memory_plan_get`)	DAG node, `task_id`, `status`, `DEPENDS_ON` edges. INDEXED.
`code`	`ingest_code(directory)` · `code_index` · `POST /code/index`	`code_search` / `code_dependencies` / `code_dead_code` · `GET /code/search`, `/code/dependencies`, `/code/dead-code`	Code entities (class/function/route). Fields: `entity_type`, `repo`.
`evaluation`	(derived from `EvaluationEvolver`)	`get_evaluation(agent_id, dimension, domain)` / `list_evaluation_history()` · `agent_evaluation_get` · `GET /agents/{agent_id}/evaluation`, `/evaluation/history`	Per-`(agent, dimension, domain)` score, bi-temporal supersession. Not user-created.
`anchor`	`ingest_structured(schema="anchor")` · `memory_anchor_set` · `POST /anchors/create`	`memory_anchor_list` · `GET /anchors/list`	`graduate` → decision · `memory_anchor_graduate`, `check_drift` / `clear`. Fields: `anchor_type`, `session_id`.

Structured & telemetry types

Schema-mapped data that bypasses the NLP pipeline via ingest_structured(data, schema=…) (MCP: memory_ingest_structured(data, schema_name=…), REST: POST /ingest/structured). Background: the Structured Memory Types section. The handler sets the ingestion strategy:

FULL: embedding + entity extraction (semantically searchable)
INDEXED: typed graph node + indexes, no embedding (queried by fields)
APPEND: minimal node, recency-only (high-volume telemetry)

Type	Strategy	Dedicated create surface (if any)	Notes / key fields
`tool_call`	APPEND	`memory_ingest_structured(schema_name="tool_call")`	Tool telemetry. Fields: `tool_name`, `result`. Read via `memory_search_by_metadata`.
`conversation_turn`	APPEND	`memory_distill` (turn-pair) / `schema="conversation_turn"`	Conversation replay rows.
`conversation`	not applicable	`ingest_conversation(turns)` · `memory_ingest_conversation` · `POST /ingest/conversation`	Session-chunked container (INDEXED) with `PART_OF` edges. See also bulk ingestion.
`document`	not applicable	`ingest_document(source)` · `memory_ingest_document` · `POST /ingest/document`	URL/file ingest, chunked.
`hook_capture`	APPEND	`schema="hook_capture"`	Hook event telemetry.
`timeline_entry`	INDEXED	`schema="timeline_entry"`	Derived FS-canonical vault timeline index.
`seed_item`	FULL	`schema="seed_item"`	Reference knowledge from seed packs (searchable).

Notes

Two recall channels. Knowledge-layer types are filtered by search(memory_type=…). Expertise-layer types come back together as a typed dict from search(query, expertise=True).
Origin tiers govern visibility. Derived types (opinion, observation, and evolver output) carry tier-3 origins, searchable but not recalled by default. See the origin taxonomy in the SmartMemory API.
Auto-classification. ingest() picks the knowledge-layer type for you. Pass memory_type= to add() to force one.