> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onelamp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Context tools

> save_context, save_session, get_context, list_context, resume_session, forget_context.

The core tools every connected agent shares — a remember / recall / list / resume
/ forget surface, and the entire MCP tool set (pure memory CRUD). They operate on your
[context memory](/concepts/context-memory) and are scoped to you on every call.

## save\_context

Save something worth remembering across tools and sessions. **Idempotent** —
saving the same content twice returns the same id with `deduped: true`.

### Parameters

<ParamField path="content" type="string" required>
  The thing to remember.
</ParamField>

<ParamField path="memory_type" type="string" default="fact">
  The canonical memory type, which drives retrieval behavior:

  * `fact` — atomic, stable knowledge ("the project uses GraphQL").
  * `event` — something that happened at a time (a deployment, a decision).
  * `instruction` — how to do something (a procedure, workflow, runbook).
  * `task` — what's being worked on right now. **Ephemeral**: it auto-expires
    after a TTL (7 days) and is swept on the next write. It's still embedded, so
    it's semantically retrievable while live.

  Defaults to `fact` (a `kind` of `decision` defaults to `event`).
</ParamField>

<ParamField path="kind" type="string" default="note">
  Finer-grained display flavor: `fact`, `decision`, `preference`, or `note`.
</ParamField>

<ParamField path="topic" type="string">
  A stable topic this entry is about (e.g. `deploy-schedule`,
  `editor-preference`). A newer entry with the same topic **supersedes** older
  ones — latest wins. Use it when updating a fact the user stated before.
</ParamField>

<ParamField path="source_surface" type="string">
  Where this came from, e.g. `claude-code`, `chatgpt`, `cursor`.
</ParamField>

<ParamField path="tags" type="string[]">
  Optional freeform tags.
</ParamField>

<ParamField path="project" type="string">
  Target a [project](/concepts/projects) (a named context bucket) by its **id or
  slug**. The entry lands in that project instead of your personal context; omit
  for personal.
</ParamField>

### Returns

<ResponseField name="id" type="string">
  The id of the saved (or matched) entry.
</ResponseField>

<ResponseField name="deduped" type="boolean">
  `true` when the content already existed and was deduplicated.
</ResponseField>

```json Example result theme={null}
{ "id": "ctx_8f2a…", "deduped": false }
```

## save\_session

Persist what a whole session taught — comprehensively. Pass the transcript or a
digest and OneLamp **distills** it into the reusable facts, events, instructions,
and tasks worth keeping, classifies each, and saves them (deduped). This is the
comprehensive backstop to per-fact `save_context`, and matters most for tools
without lifecycle hooks. Idle chatter and secrets are skipped.

### Parameters

<ParamField path="transcript" type="string" required>
  The session transcript, or a concise digest of everything durable the user
  revealed.
</ParamField>

<ParamField path="source_surface" type="string">
  Which tool this came from, e.g. `claude-code`, `codex`, `cursor`.
</ParamField>

<ParamField path="project" type="string">
  Distill the session into a [project](/concepts/projects) (id or slug) instead of
  your personal context. Omit for personal.
</ParamField>

### Returns

<ResponseField name="saved" type="number">New entries saved.</ResponseField>
<ResponseField name="deduped" type="number">Items already known.</ResponseField>
<ResponseField name="total" type="number">Items distilled from the session.</ResponseField>

<ResponseField name="session_id" type="string">
  The id of the recorded session digest (present when anything durable was saved),
  for later [`resume_session`](#resume-session).
</ResponseField>

## get\_context

Retrieve relevant context as a **ranked pack of chunks** (semantic + keyword +
exact fact-key retrieval, fused with weighted RRF). Returns source material to
reason over — **not** an answer. An empty store returns an empty pack, never an
error.

### Parameters

<ParamField path="query" type="string" required>
  What to retrieve context about.
</ParamField>

<ParamField path="max_results" type="integer" default="8">
  Maximum context chunks to return (1–50).
</ParamField>

<ParamField path="memory_types" type="string[]">
  Restrict results to these memory types (`fact`, `event`, `instruction`,
  `task`) — e.g. just `instruction` for runbooks. Omit to retrieve across all
  types.
</ParamField>

<ParamField path="scope" type="string" default="all">
  Which context store(s) to read from: `personal` (your own), `team` (every team you
  belong to), `team:<id>` (one specific team you're a member of), or `all` (personal
  **+** your teams, fused with personal winning ties). See [Teams](/concepts/teams).
</ParamField>

<ParamField path="project" type="string">
  Read from a [project](/concepts/projects) (id or slug). The project is **fused
  with your always-on personal context** (personal is the base), exactly as teams
  fuse — so a project read still surfaces relevant personal context. Omit for
  personal only.
</ParamField>

<ParamField path="verified_only" type="boolean" default="false">
  If true, return only **verified** team learnings (ones a 2nd teammate has
  independently corroborated), dropping unverified and contested ones. Your personal
  context is always included. Default returns all, trust-weighted.
</ParamField>

<ParamField path="recency" type="boolean" default="false">
  If true, strongly favor the **most recent** context over the most relevant —
  for "what was I just working on" / "what's the latest" reads. Default is
  relevance-ranked, with recency only as a tie-breaker.
</ParamField>

### Returns

<ResponseField name="packs" type="object[]">
  The ranked context chunks. Each pack has:

  <Expandable title="pack fields">
    <ResponseField name="id" type="string">The chunk's id.</ResponseField>
    <ResponseField name="text" type="string">The context text.</ResponseField>
    <ResponseField name="kind" type="string">The entry kind (`fact`, `decision`, …).</ResponseField>
    <ResponseField name="memory_type" type="string">The memory type (`fact`, `event`, `instruction`, `task`).</ResponseField>
    <ResponseField name="source_surface" type="string">Where it was saved from.</ResponseField>
    <ResponseField name="ts" type="number">Save timestamp.</ResponseField>
    <ResponseField name="score" type="number">Relevance score.</ResponseField>
    <ResponseField name="scope" type="string">Which store it came from (`personal` / `team:<id>`).</ResponseField>
    <ResponseField name="contributed_by" type="string">Team packs only: the member who promoted it.</ResponseField>
    <ResponseField name="trust" type="string">Team packs only: `verified` / `unverified` / `contested`.</ResponseField>
  </Expandable>
</ResponseField>

```json Example result theme={null}
{
  "packs": [
    {
      "id": "ctx_8f2a…",
      "text": "Use pnpm, never npm",
      "kind": "preference",
      "memory_type": "fact",
      "source_surface": "claude-code",
      "ts": 1733500000000,
      "score": 0.8123
    }
  ]
}
```

## list\_context

Browse your saved memory, newest first — each item's id, title, kind,
`memory_type`, category, a short text preview, and **cross-agent reuse**
(`reuse_count` and `last_used_surface` — how often it's been retrieved and the
tool that last used it). Use it to see what's stored (e.g. to find an id to
forget). For relevance-ranked retrieval use `get_context`.

<ParamField path="limit" type="integer" default="50">
  Maximum items to list (1–200).
</ParamField>

<ParamField path="project" type="string">
  List a [project](/concepts/projects)'s items (id or slug) instead of personal.
  Omit for personal.
</ParamField>

## resume\_session

Pick up cross-tool work where you left off. Each session digest is recorded by
[`save_session`](#save-session) in any tool, so this is the cross-agent handoff
path. Without a `session_id`, returns your most recent sessions (recency-ranked).
With one, loads that session in full — its label/summary and the learnings it
produced.

<ParamField path="session_id" type="string">
  Load one session in full by id (from a prior `resume_session` / `save_session`).
</ParamField>

<ParamField path="limit" type="integer" default="5">
  How many recent session digests to list (1–50). Ignored with `session_id`.
</ParamField>

<ParamField path="since" type="number">
  Only list sessions at/after this epoch-ms timestamp.
</ParamField>

<ParamField path="source_surface" type="string">
  Only list sessions from this surface, e.g. `claude-code`, `cursor`, `codex`.
</ParamField>

## forget\_context

Delete one saved memory by id — completely and immediately (the index row, the R2
source, and the vector). Get the id from `get_context` or `list_context`. To
instead **replace** a fact that changed, prefer `save_context` with a stable
`topic` (supersession keeps history); use `forget_context` to remove for good.

<ParamField path="id" type="string" required>
  The id of the memory to delete.
</ParamField>

<ParamField path="confirm" type="boolean" default="true">
  Pass `false` to **preview** the target without deleting it — returns what would
  be removed so you can confirm first.
</ParamField>

<ParamField path="project" type="string">
  Delete from a [project](/concepts/projects) (id or slug) instead of personal.
  Omit for personal.
</ParamField>

<ResponseField name="forgotten" type="boolean">
  `true` if an entry was deleted; `false` if the id wasn't found (or on a preview).
</ResponseField>

<Note>
  These tools embody OneLamp's core principle: writes can dedupe and supersede,
  reads are retrieval-only, and your data is always exportable (export lives in
  the OneLamp web app, not as an agent tool). See
  [Privacy & data ownership](/concepts/privacy).
</Note>