# Episodic Memory

Every registered episodic memory instance operation, with source-derived inputs, outputs, access policy, and errors.

Source: https://docs.minds.sh/docs/api/instance/episodic-memory



This reference covers **5 HTTP operations** registered by the Akasha daemon. Call these paths on your instance base URL. See [authentication](/docs/api/instance/authentication), [errors](/docs/api/instance/errors), and [coverage](/docs/api/instance/coverage) before integrating.

| Method   | Path                         | Operation                                               |
| -------- | ---------------------------- | ------------------------------------------------------- |
| `POST`   | `/v1/memory/episodic`        | [Memory episodic insert](#post-v1-memory-episodic)      |
| `GET`    | `/v1/memory/episodic/:id`    | [Memory episodic get](#get-v1-memory-episodic-id)       |
| `PUT`    | `/v1/memory/episodic/:id`    | [Memory episodic update](#put-v1-memory-episodic-id)    |
| `DELETE` | `/v1/memory/episodic/:id`    | [Memory episodic delete](#delete-v1-memory-episodic-id) |
| `POST`   | `/v1/memory/episodic/search` | [Episodic search](#post-v1-memory-episodic-search)      |

<a id="post-v1-memory-episodic" />

## POST `/v1/memory/episodic` [#post-v1memoryepisodic]

Memory episodic insert

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_memory`                     |
| Runtime service      | `memory`                                   |
| Handler dependencies | See handler source and return expressions. |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request]

**Json** — `EpisodicInsertRequest`

| Field   | Rust type       | Required on input | Notes |
| ------- | --------------- | ----------------- | ----- |
| `event` | `EpisodicEvent` | Yes               |       |

```rust
struct EpisodicInsertRequest {
    event: EpisodicEvent,
}
```

### Response [#response]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
serde_json::json!({"id": id})
```

### Errors and validation [#errors-and-validation]

Directly referenced error variants: `InvalidRequest`. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn memory_episodic_insert(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<EpisodicInsertRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        state.usage_emitter.emit_cognitive_op("memory");
        let id = db
            .episodic_insert(req.event)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"id": id})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:7465`. Registration: `akasha-daemon/src/main.rs:4635`.

<a id="get-v1-memory-episodic-id" />

## GET `/v1/memory/episodic/:id` [#get-v1memoryepisodicid]

Memory episodic get

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_memory`                     |
| Runtime service      | `memory`                                   |
| Handler dependencies | See handler source and return expressions. |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request-1]

**Path** — `String`

```json
{
  "type": "string"
}
```

### Response [#response-1]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
serde_json::json!({"item": item})
```

### Errors and validation [#errors-and-validation-1]

Directly referenced error variants: `InvalidRequest`. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn memory_episodic_get(
        Path(id): Path<String>,
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let uid =
            uuid::Uuid::parse_str(&id).map_err(|_| DaemonError::InvalidRequest("invalid id".into()))?;
        let item = db
            .episodic_get(&uid)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"item": item})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:7479`. Registration: `akasha-daemon/src/main.rs:4636`.

<a id="put-v1-memory-episodic-id" />

## PUT `/v1/memory/episodic/:id` [#put-v1memoryepisodicid]

Memory episodic update

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_memory`                     |
| Runtime service      | `memory`                                   |
| Handler dependencies | See handler source and return expressions. |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request-2]

**Path** — `String`

```json
{
  "type": "string"
}
```

**Json** — `EpisodicUpdateRequest`

| Field   | Rust type       | Required on input | Notes |
| ------- | --------------- | ----------------- | ----- |
| `event` | `EpisodicEvent` | Yes               |       |

```rust
struct EpisodicUpdateRequest {
    event: EpisodicEvent,
}
```

### Response [#response-2]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
serde_json::json!({"ok": true})
```

### Errors and validation [#errors-and-validation-2]

Directly referenced error variants: `InvalidRequest`. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn memory_episodic_update(
        Path(id): Path<String>,
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<EpisodicUpdateRequest>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let uid =
            uuid::Uuid::parse_str(&id).map_err(|_| DaemonError::InvalidRequest("invalid id".into()))?;
        db.episodic_update(&uid, &req.event)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"ok": true})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:7499`. Registration: `akasha-daemon/src/main.rs:4636`.

<a id="delete-v1-memory-episodic-id" />

## DELETE `/v1/memory/episodic/:id` [#delete-v1memoryepisodicid]

Memory episodic delete

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_memory`                     |
| Runtime service      | `memory`                                   |
| Handler dependencies | See handler source and return expressions. |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request-3]

**Path** — `String`

```json
{
  "type": "string"
}
```

### Response [#response-3]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
serde_json::json!({"ok": true})
```

### Errors and validation [#errors-and-validation-3]

Directly referenced error variants: `InvalidRequest`. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn memory_episodic_delete(
        Path(id): Path<String>,
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        let uid =
            uuid::Uuid::parse_str(&id).map_err(|_| DaemonError::InvalidRequest("invalid id".into()))?;
        db.episodic_delete(&uid)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"ok": true})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:7514`. Registration: `akasha-daemon/src/main.rs:4636`.

<a id="post-v1-memory-episodic-search" />

## POST `/v1/memory/episodic/search` [#post-v1memoryepisodicsearch]

Episodic search

| Availability         | Source contract                            |
| -------------------- | ------------------------------------------ |
| Registration         | `config.enable_memory`                     |
| Runtime service      | `memory`                                   |
| Handler dependencies | See handler source and return expressions. |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped.

### Request [#request-4]

**Json** — `EpisodicSearchReq`

| Field   | Rust type        | Required on input         | Notes |
| ------- | ---------------- | ------------------------- | ----- |
| `text`  | `Option<String>` | No; optional or defaulted |       |
| `query` | `Option<String>` | No; optional or defaulted |       |
| `limit` | `Option<usize>`  | No; optional or defaulted |       |

```rust
struct EpisodicSearchReq {
    text: Option<String>,
    query: Option<String>,
    limit: Option<usize>,
}
```

### Response [#response-4]

**Declared return:** `Result<impl IntoResponse, DaemonError>`

The following are the exact JSON construction expressions in the handler. Values such as `rows`, `result`, and delegated types are runtime values, not literal example payloads.

```rust
serde_json::to_value(rows).unwrap_or(serde_json::json!([])),
```

### Errors and validation [#errors-and-validation-4]

Directly referenced error variants: `InvalidRequest`. Middleware and delegated services can return additional errors described in the shared error reference.

<Accordions>
  <Accordion title="Inspect implementation">
    This exact source excerpt includes validation, defaults, delegated calls, and response assembly.

    ```rust
    async fn episodic_search(
        Extension(db): Extension<Arc<AkashaDB>>,
        State(_state): State<AppState>,
        Json(req): Json<EpisodicSearchReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        _state.usage_emitter.emit_cognitive_op("memory");
        let search_text = req.text.or(req.query).unwrap_or_default();
        let mut q = akasha_memory::Query::new().with_text(search_text);
        if let Some(l) = req.limit {
            q = q.with_limit(l);
        }
        let rows = db
            .episodic_search(q)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(
            serde_json::to_value(rows).unwrap_or(serde_json::json!([])),
        ))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:8635`. Registration: `akasha-daemon/src/main.rs:4698`.