Memory Operations

Auxiliary surfaces beyond add / ingest / search. Each is a real SmartMemory route family with its own SDK methods.

Anchors — anti-drift requirements

An anchor is a structured commitment (spec, scope, decision, constraint) that the agent should not violate. The drift checker compares recent outputs against active anchors and surfaces the ones that may have been broken.

# REST
POST   /memory/anchors/create
GET    /memory/anchors/list?session_id=...&anchor_type=spec
DELETE /memory/anchors/clear?session_id=...
POST   /memory/anchors/graduate
POST   /memory/anchors/check-drift

CLI mirror:

smartmemory-core anchor "Retries must be idempotent" --type constraint --session sprint-42
smartmemory-core anchors --session sprint-42
smartmemory-core anchor-clear --session sprint-42

The drift route accepts an array of recent output strings and returns each anchor with a drift_score and drift_detected_at. Use graduate to promote a satisfied anchor to long-term memory once the work is done.

Source: smart-memory-service/memory_service/api/routes/anchors.py, smart-memory-core/smartmemory/anchors/manager.py.

Feedback — explicit recall reinforcement

After surfacing recalled items, send back whether they were helpful, misleading, or neutral. The route bumps each item's retention_score and, on helpful outcomes with multiple items, strengthens CO_RETRIEVED edges between every pair (Hebbian co-retrieval).

await client.memories.feedback(
  ['item_123', 'item_456', 'item_789'],
  'helpful',
  'why did we pick FalkorDB?',
);
// → { updated: 3, edges_strengthened: 3, outcome: 'helpful' }

Source: routes/feedback.py. The boost (+2) intentionally outweighs implicit co-retrieval (which increments by 1) so explicit user signal wins.

Failures journal — episodic memory of bugs

Log failures so the agent doesn't repeat them. Each failure becomes an episodic memory with origin="failure:agent".

POST /memory/failures/log
{
  "error_type": "TimeoutError",
  "content": "Connection timed out after 30s",
  "context": "Pulling Docker image x/y:tag",
  "plan_id": "plan_abc",        # optional
  "task_id": "task_42",         # optional
  "attempted_fix": "Increased pull timeout to 60s",
  "resolution": "Switched mirror"
}

POST /memory/failures/check
{
  "error_type": "TimeoutError",
  "context": "Pulling Docker image",
  "top_k": 3
}
# → ranked prior failures with the same shape

Source: routes/failures.py, smartmemory/plans/failure_journal.py.

Agents — first-class agent users

Agents are users with API keys instead of passwords. Use them to give an autonomous worker its own memory partition and audit trail.

POST   /memory/agents          # create
GET    /memory/agents          # list
GET    /memory/agents/{id}
DELETE /memory/agents/{id}
GET    /memory/agents/{id}/recall-profile
PUT    /memory/agents/{id}/recall-profile

agent_config is a free-form dict (model, capabilities, tool list). recall-profile controls which memory types and origins the agent sees on search. Agents can be assigned to teams via the standard team APIs.

Source: routes/agents.py.

Links — explicit relations

Beyond the relations the pipeline extracts, you can create explicit links:

POST /memory/link            # link two memory items
{ "source_id": "...", "target_id": "...", "link_type": "RELATED" }

POST /memory/edge            # create a typed graph edge with properties
GET  /memory/{item_id}/links
GET  /memory/{item_id}/neighbors

POST /memory/link validates ownership of both endpoints — you can only link items inside your active workspace. POST /memory/edge is the lower-level form that lets you set arbitrary edge properties (used by Studio for manual graph curation).

Source: routes/links.py.

Archive — conversation artifacts

Persist a JSON conversation payload outside the graph for compliance / replay use. Returns a content-hash-addressable URI.

POST /memory/archive/store
{
  "conversation_id": "conv_abc",
  "payload": { "turns": [...] },
  "metadata": { "source": "maya" }
}
# → { archive_uri: "...", content_hash: "..." }

GET /memory/archive/{archive_uri}

The archive lives in MongoDB; the graph row only carries the URI.

Source: routes/archive.py.

Clustering — entity deduplication

When ingestion produces duplicate entities (e.g. "John Smith" / "J. Smith"), run clustering to merge them by vector similarity:

POST /memory/clustering/run?distance_threshold=0.1&dry_run=true
GET  /memory/clustering/stats

dry_run=true previews clusters without merging. Lower distance_threshold is stricter (fewer merges); 0.1 is the default. Always dry_run first on a new workspace to verify the merges look right.

Source: routes/clustering.py.

Analytics — bias, origins, drift

/memory/analytics/* exposes a few diagnostic views over the workspace:

Bias analysis requires the optional scikit-learn dependency — if it's absent, the route 503s with a helpful message.

Source: routes/analytics.py.

See also

• JavaScript SDK — typed wrappers for these routes
• Decisions lifecycle walkthrough