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.

Type	Create (SDK · MCP · REST)	Query	Lifecycle & key fields
`decision`	`add_decision(content, …)` · `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: `rationale`, `rejected_alternatives`, `constraints`, `confidence`, `decision_type`, `domain`, `status`. 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 + supersession. Also `reasoning_challenge`, `reasoning_proof_tree`.
`constraint`	`add_constraint(content)` / `ingest_structured(schema="constraint")` · `memory_ingest_structured` · `POST /ingest/structured`	`search(expertise=True)["constraint"]`	Hard rule discovered or imposed. Fields: `domain`, `source`.
`learned`	`add_learning(content)` / `ingest_structured(schema="learned")` · `memory_ingest_structured` · `POST /ingest/structured`	`search(expertise=True)["learned"]`	A lesson learned the hard way. Fields: `lesson`, `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 — `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`	—	`ingest_conversation(turns)` · `memory_ingest_conversation` · `POST /ingest/conversation`	Session-chunked container (INDEXED) with `PART_OF` edges. See also bulk ingestion.
`document`	—	`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.