# Cognitive Memory

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

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



This reference covers **9 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/cognitive/query`           | [Memory cognitive query](#post-v1-memory-cognitive-query)                    |
| `POST` | `/v1/memory/cognitive/thought`         | [Memory cognitive thought](#post-v1-memory-cognitive-thought)                |
| `POST` | `/v1/memory/cognitive/decision`        | [Memory cognitive decision](#post-v1-memory-cognitive-decision)              |
| `POST` | `/v1/memory/cognitive/interaction`     | [Memory cognitive interaction](#post-v1-memory-cognitive-interaction)        |
| `POST` | `/v1/memory/cognitive/session`         | [Memory cognitive session](#post-v1-memory-cognitive-session)                |
| `POST` | `/v1/memory/cognitive/resource`        | [Memory cognitive resource](#post-v1-memory-cognitive-resource)              |
| `POST` | `/v1/memory/cognitive/usage`           | [Memory cognitive usage](#post-v1-memory-cognitive-usage)                    |
| `POST` | `/v1/memory/cognitive/resources`       | [Memory cognitive resource store](#post-v1-memory-cognitive-resources)       |
| `POST` | `/v1/memory/cognitive/resources/usage` | [Memory cognitive resource usage](#post-v1-memory-cognitive-resources-usage) |

<a id="post-v1-memory-cognitive-query" />

## POST `/v1/memory/cognitive/query` [#post-v1memorycognitivequery]

Memory cognitive query

| 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** — `CognitiveQueryReq`

| Field   | Rust type           | Required on input | Notes |
| ------- | ------------------- | ----------------- | ----- |
| `query` | `serde_json::Value` | Yes               |       |

```rust
struct CognitiveQueryReq {
    query: serde_json::Value,
}
```

**JSON field accesses in handler:** `agent_id`, `end_time`, `include_decisions`, `include_interactions`, `include_sessions`, `include_thoughts`, `min_confidence`, `start_time`. Nested lookups are included; this list alone does not establish requiredness.

### 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!({
        "thoughts": res.thoughts.len(),
        "decisions": res.decisions.len(),
        "interactions": res.interactions.len(),
        "sessions": res.sessions.len()
    })
```

### 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_cognitive_query(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<CognitiveQueryReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        state.usage_emitter.emit_cognitive_op("query");
        // Map JSON to CognitiveQuery fields
        let mut q = CognitiveQuery::new();
        if let Some(agent) = req.query.get("agent_id").and_then(|v| v.as_str()) {
            q.agent_id = Some(agent.to_string());
        }
        if let Some(start) = req
            .query
            .get("start_time")
            .and_then(|v| v.as_str())
            .and_then(|s| chrono::DateTime::parse_from_rfc3339(s).ok())
            .map(|t| t.with_timezone(&chrono::Utc))
        {
            q.start_time = Some(start);
        }
        if let Some(end) = req
            .query
            .get("end_time")
            .and_then(|v| v.as_str())
            .and_then(|s| chrono::DateTime::parse_from_rfc3339(s).ok())
            .map(|t| t.with_timezone(&chrono::Utc))
        {
            q.end_time = Some(end);
        }
        if let Some(minc) = req.query.get("min_confidence").and_then(|v| v.as_f64()) {
            q.min_confidence = Some(minc as f32);
        }
        if let Some(bt) = req.query.get("include_thoughts").and_then(|v| v.as_bool()) {
            q.include_thoughts = bt;
        }
        if let Some(bd) = req.query.get("include_decisions").and_then(|v| v.as_bool()) {
            q.include_decisions = bd;
        }
        if let Some(bi) = req
            .query
            .get("include_interactions")
            .and_then(|v| v.as_bool())
        {
            q.include_interactions = bi;
        }
        if let Some(bs) = req.query.get("include_sessions").and_then(|v| v.as_bool()) {
            q.include_sessions = bs;
        }
        let res = db
            .cognitive_query(q)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({
            "thoughts": res.thoughts.len(),
            "decisions": res.decisions.len(),
            "interactions": res.interactions.len(),
            "sessions": res.sessions.len()
        })))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:7740`. Registration: `akasha-daemon/src/main.rs:4666`.

<a id="post-v1-memory-cognitive-thought" />

## POST `/v1/memory/cognitive/thought` [#post-v1memorycognitivethought]

Memory cognitive thought

| 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]

**Json** — `CognitiveThoughtReq`

| Field     | Rust type          | Required on input | Notes |
| --------- | ------------------ | ----------------- | ----- |
| `thought` | `CognitiveThought` | Yes               |       |

```rust
struct CognitiveThoughtReq {
    thought: CognitiveThought,
}
```

### 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!({"id": id})
```

### 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_cognitive_thought(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<CognitiveThoughtReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        state.usage_emitter.emit_cognitive_op("thought");
        let id = db
            .cognitive_log_thought(req.thought)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"id": id})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:7663`. Registration: `akasha-daemon/src/main.rs:4667`.

<a id="post-v1-memory-cognitive-decision" />

## POST `/v1/memory/cognitive/decision` [#post-v1memorycognitivedecision]

Memory cognitive decision

| 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]

**Json** — `CognitiveDecisionReq`

| Field      | Rust type           | Required on input | Notes |
| ---------- | ------------------- | ----------------- | ----- |
| `decision` | `CognitiveDecision` | Yes               |       |

```rust
struct CognitiveDecisionReq {
    decision: CognitiveDecision,
}
```

### 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!({"id": id})
```

### 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_cognitive_decision(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<CognitiveDecisionReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        state.usage_emitter.emit_cognitive_op("decision");
        let id = db
            .cognitive_log_decision(req.decision)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"id": id})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:7682`. Registration: `akasha-daemon/src/main.rs:4671`.

<a id="post-v1-memory-cognitive-interaction" />

## POST `/v1/memory/cognitive/interaction` [#post-v1memorycognitiveinteraction]

Memory cognitive interaction

| 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]

**Json** — `CognitiveInteractionReq`

| Field         | Rust type          | Required on input | Notes |
| ------------- | ------------------ | ----------------- | ----- |
| `interaction` | `AgentInteraction` | Yes               |       |

```rust
struct CognitiveInteractionReq {
    interaction: AgentInteraction,
}
```

### 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!({"id": id})
```

### 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_cognitive_interaction(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<CognitiveInteractionReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        state.usage_emitter.emit_cognitive_op("interaction");
        let id = db
            .cognitive_log_interaction(req.interaction)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"id": id})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:7701`. Registration: `akasha-daemon/src/main.rs:4675`.

<a id="post-v1-memory-cognitive-session" />

## POST `/v1/memory/cognitive/session` [#post-v1memorycognitivesession]

Memory cognitive session

| 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** — `CognitiveSessionReq`

| Field      | Rust type | Required on input | Notes |
| ---------- | --------- | ----------------- | ----- |
| `agent_id` | `String`  | Yes               |       |
| `goal`     | `String`  | Yes               |       |

```rust
struct CognitiveSessionReq {
    agent_id: String,
    goal: String,
}
```

### 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::json!({"session": sess})
```

### 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 memory_cognitive_session(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Json(req): Json<CognitiveSessionReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        state.usage_emitter.emit_cognitive_op("session");
        let sess = db
            .cognitive_start_session(req.agent_id, req.goal)
            .await
            .map_err(|e| DaemonError::InvalidRequest(e.to_string()))?;
        Ok(Json(serde_json::json!({"session": sess})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:7721`. Registration: `akasha-daemon/src/main.rs:4679`.

<a id="post-v1-memory-cognitive-resource" />

## POST `/v1/memory/cognitive/resource` [#post-v1memorycognitiveresource]

Memory cognitive resource

| 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-5]

**Json** — `serde_json::Value`

This handler accepts dynamic JSON. The field accesses below are source observations, not a fabricated required-field schema.

### Response [#response-5]

**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-5]

Directly referenced error variants: none in the handler body. 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_cognitive_resource(
        State(state): State<AppState>,
        Extension(_db): Extension<Arc<AkashaDB>>,
        Json(_req): Json<serde_json::Value>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        Ok(Json(serde_json::json!({"ok": true})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:7806`. Registration: `akasha-daemon/src/main.rs:4683`.

<a id="post-v1-memory-cognitive-usage" />

## POST `/v1/memory/cognitive/usage` [#post-v1memorycognitiveusage]

Memory cognitive usage

| 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-6]

**Json** — `serde_json::Value`

This handler accepts dynamic JSON. The field accesses below are source observations, not a fabricated required-field schema.

### Response [#response-6]

**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-6]

Directly referenced error variants: none in the handler body. 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_cognitive_usage(
        State(state): State<AppState>,
        Extension(_db): Extension<Arc<AkashaDB>>,
        Json(_req): Json<serde_json::Value>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        Ok(Json(serde_json::json!({"ok": true})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:7815`. Registration: `akasha-daemon/src/main.rs:4687`.

<a id="post-v1-memory-cognitive-resources" />

## POST `/v1/memory/cognitive/resources` [#post-v1memorycognitiveresources]

Memory cognitive resource store

| 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-7]

**Json** — `serde_json::Value`

This handler accepts dynamic JSON. The field accesses below are source observations, not a fabricated required-field schema.

### Response [#response-7]

**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-7]

Directly referenced error variants: none in the handler body. 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_cognitive_resource_store(
        State(state): State<AppState>,
        Extension(_db): Extension<Arc<AkashaDB>>,
        Json(_req): Json<serde_json::Value>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        Ok(Json(serde_json::json!({"ok": true})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:7824`. Registration: `akasha-daemon/src/main.rs:4688`.

<a id="post-v1-memory-cognitive-resources-usage" />

## POST `/v1/memory/cognitive/resources/usage` [#post-v1memorycognitiveresourcesusage]

Memory cognitive resource usage

| 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-8]

**Json** — `serde_json::Value`

This handler accepts dynamic JSON. The field accesses below are source observations, not a fabricated required-field schema.

### Response [#response-8]

**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-8]

Directly referenced error variants: none in the handler body. 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_cognitive_resource_usage(
        State(state): State<AppState>,
        Extension(_db): Extension<Arc<AkashaDB>>,
        Json(_req): Json<serde_json::Value>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        Ok(Json(serde_json::json!({"ok": true})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:7833`. Registration: `akasha-daemon/src/main.rs:4692`.