Skip to main content

Memory

Memory lets the agent retain context across sessions. Use the workflow tools to recall prior context before starting work, then capture meaningful outcomes when the task is done.

Workflow tools​

These three tools form the core memory loop: load context, do work, save results.

localnest_task_context​

Returns relevant memories for the current task based on the active project, recent history, and any prior outcomes.

Call this at the start of every session before analysis or code changes.

Use when

Beginning a new task or resuming a previous session. This is the recommended first memory call.

localnest_capture_outcome​

Persists a meaningful result (fix applied, decision made, preference discovered) so future sessions can recall it.

Useful parameters:

  • outcome — free-text description of what happened
  • tags — categorization labels for retrieval
  • nest / branch — optional scoping for organized retrieval

Use when

A task is complete and the result should inform future work. Avoid capturing trivial or intermediate steps.

localnest_memory_recall​

Retrieves memories matching a natural-language query. Supports filtering by nest, branch, tags, and agent.

Useful parameters:

  • query — what to recall
  • nest / branch — scope filter
  • agent_id — restrict to a specific agent's memories
  • limit — max results

Use when

You need targeted recall beyond what task_context returns automatically.

CRUD operations​

localnest_memory_store

Create a new memory entry with content, tags, and optional nest/branch scoping.

localnest_memory_update

Update an existing memory by ID. Accepts partial updates to content, tags, or metadata.

localnest_memory_delete

Remove a memory by ID. Permanent and not reversible.

localnest_memory_get

Retrieve a single memory by its exact ID. Returns full content and metadata.

localnest_memory_list

List memories with optional filtering by nest, branch, tags, or agent. Supports pagination.

localnest_memory_status

Returns memory subsystem health: total count, storage backend, and configuration state.

Relations​

Relations link memories together so you can traverse connected context.

localnest_memory_suggest_relations

Suggest potential relations for a memory based on content similarity. Review before accepting.

localnest_memory_add_relation

Create a typed link between two memories (e.g., related_to, supersedes, caused_by).

localnest_memory_remove_relation

Remove an existing relation between two memories.

localnest_memory_related

Retrieve all memories related to a given memory ID, following relation links.

Events​

Events capture timestamped occurrences that may not warrant a full memory entry.

localnest_memory_capture_event​

Record a discrete event (build failure, deployment, config change) with structured metadata.

localnest_memory_events​

List captured events with optional filtering by type, time range, or tags.

Duplicate detection​

localnest_memory_check_duplicate​

Check whether a proposed memory is semantically similar to an existing entry before storing. Helps avoid redundant memories when ingesting conversation history or bulk data.

Use when

Ingesting external data via localnest_ingest_markdown or localnest_ingest_json, or when programmatically storing memories in a loop.

CLI commands​

# Add a memory from the command line
localnest memory add "Switched auth to JWT with refresh tokens" --tags auth,security

# Search memories by query
localnest memory search "authentication approach"

# List all memories (optionally filtered)
localnest memory list --nest my-project --limit 20

# Show a specific memory by ID
localnest memory show <memory-id>

# Delete a memory
localnest memory delete <memory-id>
1
Recall before acting

Call localnest_task_context at the start of every session to load relevant prior context.

2
Query when needed

Use localnest_memory_recall for targeted lookups during the task when you need specific prior knowledge.

3
Capture durable outcomes

After completing meaningful work, call localnest_capture_outcome so future sessions benefit.

4
Link related memories

Use localnest_memory_suggest_relations to discover connections, then localnest_memory_add_relation to persist them.

tip

Prefer localnest_task_context over localnest_memory_recall as your first call. Task context automatically aggregates the most relevant memories for the current workspace and recent history.