Memorize & Recall

Three operations form the core of Kanoniv memory: memorize stores knowledge linked to entities, recall retrieves all memory for an entity, and search_memory finds memory across the entire tenant.

Memorize

Store a memory entry linked to one or more entities. The entry persists across sessions, machines, and agent restarts. Any agent that resolves the same entity will receive this memory.

MCP

json

{
  "tool": "memorize",
  "arguments": {
    "entry_type": "decision",
    "title": "Qualified as enterprise lead",
    "content": "Company has 500+ employees, ARR > $10M. Matches ICP.",
    "entity_ids": ["ENT_7f82"]
  }
}

Python SDK

python

import kanoniv

mem = kanoniv.get_memory(agent_name="qualifier-agent")

mem.memorize(
    "Company has 500+ employees, ARR > $10M. Matches ICP.",
    title="Qualified as enterprise lead",
    entry_type="decision",
    entity_fields={"email": "[email protected]"},
)

REST API

bash

POST /v1/memory
Content-Type: application/json
Authorization: Bearer <api_key>

{
  "entry_type": "decision",
  "slug": "lead-qualified-ent-7f82",
  "title": "Qualified as enterprise lead",
  "content": "Company has 500+ employees, ARR > $10M. Matches ICP.",
  "linked_entities": ["ENT_7f82"],
  "author": "qualifier-agent"
}

Parameters

Parameter	Type	Required	Description
`entry_type`	string	Yes	One of: `decision`, `investigation`, `pattern`, `knowledge`
`title`	string	Yes	Short summary (max 500 chars)
`content`	string	No	Detailed content
`entity_ids`	string[]	No	Entity UUIDs to link this memory to
`source_names`	string[]	No	Source names related to this memory

Entry types

Each memory entry has a type that describes its purpose. Agents use these types to filter and prioritize information.

decision

An action taken or conclusion reached. These are the most operationally significant entries - they record what an agent decided and why.

json

{
  "tool": "memorize",
  "arguments": {
    "entry_type": "decision",
    "title": "Marked as do-not-contact",
    "content": "Customer requested removal from all outreach on 2026-03-10. Legal hold.",
    "entity_ids": ["ENT_9a3b"]
  }
}

Examples: "Qualified as sales lead," "Approved for enterprise pricing," "Flagged for compliance review," "Merged with duplicate entity."

investigation

Research findings or enrichment data. These record what an agent learned during a research process.

json

{
  "tool": "memorize",
  "arguments": {
    "entry_type": "investigation",
    "title": "Enriched via LinkedIn",
    "content": "VP Engineering at Acme Corp. 12 years experience. Active on GitHub. Previously at Stripe.",
    "entity_ids": ["ENT_7f82"]
  }
}

Examples: "Enriched via LinkedIn," "Verified address via USPS," "Cross-referenced with D&B data."

pattern

A recurring observation about an entity. Patterns are discovered over time as memory accumulates.

json

{
  "tool": "memorize",
  "arguments": {
    "entry_type": "pattern",
    "title": "Always uses personal email for signups",
    "content": "This contact has signed up 3 times with personal email, never corporate. Route all comms to personal address.",
    "entity_ids": ["ENT_7f82"]
  }
}

Examples: "Purchases quarterly," "Responds fastest on Slack," "Always disputes first invoice."

knowledge

Project documentation and shared context. Unlike the other types, knowledge entries are typically not linked to specific entities - they provide background that all agents benefit from.

json

{
  "tool": "memorize",
  "arguments": {
    "entry_type": "knowledge",
    "title": "CRM field mapping conventions",
    "content": "Salesforce Account.Name maps to company. Contact.Email maps to email. Always use Contact.MobilePhone over Account.Phone."
  }
}

Knowledge entries are often created via sync_knowledge (bulk import) rather than individual memorize calls. See Coordination.

The author field

Every memory entry records which agent created it via the author field. This is set automatically from KANONIV_AGENT_NAME (MCP) or the agent_name parameter (Python SDK).

json

{
  "entry_type": "decision",
  "title": "Qualified as enterprise lead",
  "author": "qualifier-agent",
  "created_at": "2026-03-15T14:30:00Z"
}

The author field is critical for:

Attribution - knowing which agent contributed which knowledge
Expertise queries - finding agents experienced with a domain
Reputation - building verifiable track records per agent
Debugging - tracing bad decisions back to their source

Recall

Retrieve all memory entries linked to an entity. Returns decisions, investigations, patterns, knowledge, and active intents - everything agents have recorded about this entity.

MCP

json

{
  "tool": "recall",
  "arguments": {
    "entity_id": "ENT_7f82"
  }
}

Returns:

json

{
  "entries": [
    {
      "id": "mem_001",
      "entry_type": "decision",
      "title": "Qualified as enterprise lead",
      "content": "Company has 500+ employees, ARR > $10M.",
      "author": "qualifier-agent",
      "status": "active",
      "created_at": "2026-03-15T14:30:00Z"
    },
    {
      "id": "mem_002",
      "entry_type": "investigation",
      "title": "Enriched via LinkedIn",
      "content": "VP Engineering at Acme Corp.",
      "author": "enrichment-agent",
      "status": "active",
      "created_at": "2026-03-15T14:31:00Z"
    }
  ]
}

Python SDK

python

# By entity ID (from identity graph)
entries = mem.recall(entity_id="ENT_7f82")

# By raw fields (local fuzzy match)
entries = mem.recall(entity_fields={"email": "[email protected]"})

REST API

bash

GET /v1/memory/by-entity/ENT_7f82
Authorization: Bearer <api_key>

Resolve with memory

The most common pattern is resolving an entity and getting its memory in a single call. The resolve_with_memory MCP tool combines both operations:

json

{
  "tool": "resolve_with_memory",
  "arguments": {
    "source_name": "crm",
    "external_id": "contact_123",
    "data": { "email": "[email protected]" }
  }
}

Returns the resolved entity (entity_id, confidence, is_new) plus all linked memory. This is the recommended tool for agents that need full context before acting.

Search

Full-text search across all memory entries in the tenant. Searches titles and content.

MCP

json

{
  "tool": "search_memory",
  "arguments": {
    "q": "enterprise lead",
    "entry_type": "decision",
    "limit": 10
  }
}

Parameter	Type	Required	Description
`q`	string	Yes	Search query
`entry_type`	string	No	Filter: `decision`, `investigation`, `pattern`, `intent`, `knowledge`, `expertise`
`limit`	integer	No	Max results (default 20)

Python SDK

python

# Semantic search (if sentence-transformers installed) or FTS5 fallback
results = mem.search("enterprise lead", limit=10)

for r in results:
    print(f"[{r.entry_type}] {r.title}: {r.content}")

REST API

bash

GET /v1/memory/search?q=enterprise+lead&entry_type=decision
Authorization: Bearer <api_key>

Memory statuses

Memory entries have a lifecycle tracked by status.

Status	Meaning
`active`	Current and relevant
`superseded`	Replaced by a newer entry
`resolved`	The issue or investigation is complete
`archived`	No longer relevant, retained for audit

Update status via the REST API:

bash

PUT /v1/memory/:id
Content-Type: application/json
Authorization: Bearer <api_key>

{
  "status": "superseded"
}

Memory entries are never hard-deleted. Archiving sets the status to archived but the entry remains in the graph for audit purposes.

Memory and merges

When two entities merge, their memory entries combine. If Entity A has 3 memory entries and Entity B has 2, the merged entity has all 5. No memory is lost during merges.

This means memory accumulates naturally as the identity graph evolves. An agent that resolves a partial record (just a phone number) and stores a decision contributes context that later agents benefit from - even after the graph restructures through merges.

Example: four-agent pipeline

Agent 1 (qualification):
  resolve [email protected] -> ENT_7f82 (new)
  memorize: "Qualified as enterprise lead"

Agent 2 (enrichment):
  resolve (555) 010-1234 -> ENT_7f82 (matched by identity engine)
  recall: sees "Qualified as enterprise lead" from Agent 1
  memorize: "VP Engineering at Acme Corp"

Agent 3 (pattern detection):
  resolve [email protected] -> ENT_7f82
  recall: sees memory from Agent 1 + Agent 2
  memorize: "Always uses personal email for signups"

Agent 4 (outreach):
  resolve [email protected] -> ENT_7f82
  recall: sees memory from Agent 1 + Agent 2 + Agent 3
  Acts with full context. No coordination required.

Four agents, zero direct communication, full shared context. The identity graph is the coordination layer.

Memorize & Recall ​

Memorize ​

MCP ​

Python SDK ​

REST API ​

Parameters ​

Entry types ​

decision ​

investigation ​

pattern ​

knowledge ​

The author field ​

Recall ​

MCP ​

Python SDK ​

REST API ​

Resolve with memory ​

Search ​

MCP ​

Python SDK ​

REST API ​

Memory statuses ​

Memory and merges ​

Example: four-agent pipeline ​

Memorize & Recall

Memorize

MCP

Python SDK

REST API

Parameters

Entry types

decision

investigation

pattern

knowledge

The author field

Recall

MCP

Python SDK

REST API

Resolve with memory

Search

MCP

Python SDK

REST API

Memory statuses

Memory and merges

Example: four-agent pipeline