Neurophic
Memory

Search memory

Learn about how to search memory and the two result shapes

Retrieve is the full search. It ranks memories, patterns and recent observations against a query and returns them as Markdown for a prompt or as JSON for your code.

POST/v1/retrievehttps://api.neurophic.ai

Request

identifier
string required 1-500 characters
Your end-user id.
query
string required 1-2,000 characters
What to search for. 1-2,000 characters.
goal
stringup to 500 characters
Optional goal that biases ranking towards memories relevant to it. Up to 500 characters.
since
stringISO 8601
Only return memories observed at or after this time (ISO 8601). Patterns are not filtered by since.
limit
integer default 51-20
Maximum number of results. 1-20.
format
'markdown' | 'json' default markdown
Response shape: 'markdown' returns a ready-to-prompt string, 'json' returns structured memories and observations.

Response

200Success
result
string | object required

Failures return one of the errors listed under API reference > Errors.

Note

Results are ranked by relevance to query and goal; low-relevance results are omitted. A fact can briefly appear as both an observation and a memory (see API reference > Ingest).

Markdown

result is a string with a ## Memories section and a ## Observations section; an empty section is left out. Memory headers carry the relevance score, the claim type and, for plain memories, the id in backticks; pattern headers carry a pattern tag and a confidence instead of an id. List items starting with ← and → are causal links: what led to this memory and what it led to.

{
  "result": "## Memories\n\n### [0.81|semantic] `5f1d2c3e-0c2a-4b7e-9a1b-2f3c4d5e6f70`\nPrefers window seats and vegetarian meals on long flights.\n- ← Flew to Lisbon for the first time in March.\n\n### [0.64|predictive|pattern 0.72]\nTends to book travel several weeks ahead.\n\n## Observations\n\n### [0.55] `9a8b7c6d-1e2f-4a3b-8c9d-0e1f2a3b4c5d`\nAsked about upgrading to business class on the next trip."
}

When nothing is relevant, result is the string "No relevant memories found.".

JSON

With the json format, result holds two arrays: memories and observations. Patterns appear among the memories with isPattern: true and a confidence score but no id; causedBy and leadTo list the content of up to three linked memories each.

{
  "result": {
    "memories": [
      {
        "id": "5f1d2c3e-0c2a-4b7e-9a1b-2f3c4d5e6f70",
        "content": "Prefers window seats and vegetarian meals on long flights.",
        "claimType": "semantic",
        "relevance": 0.81,
        "causedBy": ["Flew to Lisbon for the first time in March."],
        "leadTo": [],
        "isPattern": false,
        "createdAt": "2026-08-12T09:30:00.000Z"
      },
      {
        "content": "Tends to book travel several weeks ahead.",
        "claimType": "predictive",
        "relevance": 0.64,
        "causedBy": [],
        "leadTo": [],
        "isPattern": true,
        "confidence": 0.72,
        "createdAt": "2026-08-14T02:00:00.000Z"
      }
    ],
    "observations": [
      {
        "id": "9a8b7c6d-1e2f-4a3b-8c9d-0e1f2a3b4c5d",
        "content": "Asked about upgrading to business class on the next trip.",
        "relevance": 0.55,
        "createdAt": "2026-08-19T08:15:00.000Z"
      }
    ]
  }
}

When nothing is relevant, both arrays are empty:

{
  "result": {
    "memories": [],
    "observations": []
  }
}

Note

  • Patterns have no id, so Get and Delete cannot target them. To remove a pattern, delete the memories it was built from.
  • Reads refresh the memories and patterns they return; List and Get do not.
  • createdAt on a memory is the time it was promoted, not the time the content was first sent. Decayed and superseded memories are not returned here; List still shows them.

Example

import { Neurophic } from 'neurophic';

const client = new Neurophic({ apiKey: process.env.NEUROPHIC_API_KEY });

const { result } = await client.retrieve({
  identifier: 'user-123',
  query: 'travel preferences',
  goal: 'book a flight for the user',
  limit: 10,
  format: 'json',
});

Context

Learn about how to get a prompt-ready block of relevant memories

List

Learn about how to list every stored memory