# Working Memory

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

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



This reference covers **6 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                                                           |
| ------ | --------------------------------- | ------------------------------------------------------------------- |
| `GET`  | `/v1/working-memory/slots`        | [Working memory slots list](#get-v1-working-memory-slots)           |
| `GET`  | `/v1/working-memory/config`       | [Working memory config get](#get-v1-working-memory-config)          |
| `PUT`  | `/v1/working-memory/config`       | [Working memory config update](#put-v1-working-memory-config)       |
| `GET`  | `/v1/working-memory/stats`        | [Working memory stats](#get-v1-working-memory-stats)                |
| `POST` | `/v1/working-memory/slots/clear`  | [Working memory slots clear](#post-v1-working-memory-slots-clear)   |
| `POST` | `/v1/working-memory/slots/inject` | [Working memory slots inject](#post-v1-working-memory-slots-inject) |

<a id="get-v1-working-memory-slots" />

## GET `/v1/working-memory/slots` [#get-v1working-memoryslots]

Working memory slots list

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| Runtime service      | No prefix-level service check; handler dependencies still apply. |
| Handler dependencies | See handler source and return expressions.                       |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped. Handler additionally checks require(CoreAction::Read, Some(request\_authority::MEMORY\_WORKING)); require\_matching\_db(\&db).

### Request [#request]

No typed JSON, query, or path extractor is declared in the handler signature. Headers or request objects may still be consumed; the signature below is authoritative.

### 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!({"slots": entries, "count": entries.len()}),
```

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

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 working_memory_slots_list(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Extension(authority): Extension<RequestAuthority>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require(CoreAction::Read, Some(request_authority::MEMORY_WORKING))?;
        authority.require_matching_db(&db)?;
        let mut registry = state.working_memory_slots.write().await;
        registry.prune_namespace(authority.namespace(), state.working_memory_clock.now());
        let entries: Vec<serde_json::Value> = registry
            .namespaces
            .get(&authority.namespace())
            .into_iter()
            .flat_map(|namespace| namespace.slots.iter())
            .map(|(id, slot)| serde_json::json!({"id": id, "value": slot.value}))
            .collect();
        Ok(Json(
            serde_json::json!({"slots": entries, "count": entries.len()}),
        ))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10931`. Registration: `akasha-daemon/src/main.rs:4384`.

<a id="get-v1-working-memory-config" />

## GET `/v1/working-memory/config` [#get-v1working-memoryconfig]

Working memory config get

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| Runtime service      | No prefix-level service check; handler dependencies still apply. |
| Handler dependencies | See handler source and return expressions.                       |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped. Handler additionally checks require\_operator\_control().

### Request [#request-1]

No typed JSON, query, or path extractor is declared in the handler signature. Headers or request objects may still be consumed; the signature below is authoritative.

### 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
cfg.clone()
```

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

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 working_memory_config_get(
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require_operator_control()?;
        let cfg = state.working_memory_config.read().await;
        Ok(Json(cfg.clone()))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10953`. Registration: `akasha-daemon/src/main.rs:4385`.

<a id="put-v1-working-memory-config" />

## PUT `/v1/working-memory/config` [#put-v1working-memoryconfig]

Working memory config update

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| Runtime service      | No prefix-level service check; handler dependencies still apply. |
| Handler dependencies | See handler source and return expressions.                       |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped. Handler additionally checks require\_operator\_control().

### Request [#request-2]

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

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

### 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, "config": config})
```

### 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 working_memory_config_update(
        State(state): State<AppState>,
        Extension(authority): Extension<RequestAuthority>,
        Json(body): Json<serde_json::Value>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require_operator_control()?;
        let config: WorkingMemoryConfig = serde_json::from_value(body)
            .map_err(|error| DaemonError::InvalidRequest(error.to_string()))?;
        config.validate()?;
        let mut cfg = state.working_memory_config.write().await;
        *cfg = config.clone();
        Ok(Json(serde_json::json!({"ok": true, "config": config})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10963`. Registration: `akasha-daemon/src/main.rs:4385`.

<a id="get-v1-working-memory-stats" />

## GET `/v1/working-memory/stats` [#get-v1working-memorystats]

Working memory stats

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| Runtime service      | No prefix-level service check; handler dependencies still apply. |
| Handler dependencies | See handler source and return expressions.                       |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped. Handler additionally checks require(CoreAction::Read, Some(request\_authority::MEMORY\_WORKING)); require\_matching\_db(\&db).

### Request [#request-3]

No typed JSON, query, or path extractor is declared in the handler signature. Headers or request objects may still be consumed; the signature below is authoritative.

### 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!({
        "slotCount": slot_count,
        "capacity": capacity,
        "utilizationPct": if capacity > 0 {
            (slot_count as f64 / capacity as f64 * 100.0).round()
        } else {
            0.0
        }
    })
```

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

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 working_memory_stats(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Extension(authority): Extension<RequestAuthority>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require(CoreAction::Read, Some(request_authority::MEMORY_WORKING))?;
        authority.require_matching_db(&db)?;
        let capacity = state.working_memory_config.read().await.max_slots;
        let mut registry = state.working_memory_slots.write().await;
        registry.prune_namespace(authority.namespace(), state.working_memory_clock.now());
        let slot_count = registry
            .namespaces
            .get(&authority.namespace())
            .map_or(0, |namespace| namespace.slots.len());
        Ok(Json(serde_json::json!({
            "slotCount": slot_count,
            "capacity": capacity,
            "utilizationPct": if capacity > 0 {
                (slot_count as f64 / capacity as f64 * 100.0).round()
            } else {
                0.0
            }
        })))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:10978`. Registration: `akasha-daemon/src/main.rs:4389`.

<a id="post-v1-working-memory-slots-clear" />

## POST `/v1/working-memory/slots/clear` [#post-v1working-memoryslotsclear]

Working memory slots clear

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| Runtime service      | No prefix-level service check; handler dependencies still apply. |
| Handler dependencies | See handler source and return expressions.                       |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped. Handler additionally checks require(CoreAction::Delete, Some(request\_authority::MEMORY\_WORKING)); require\_matching\_db(\&db).

### Request [#request-4]

**Json** — `WmSlotClearReq`

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

```rust
struct WmSlotClearReq {
    id: 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!({"ok": true, "removed": existed})
```

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

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 working_memory_slots_clear(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Extension(authority): Extension<RequestAuthority>,
        Json(req): Json<WmSlotClearReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require(CoreAction::Delete, Some(request_authority::MEMORY_WORKING))?;
        authority.require_matching_db(&db)?;
        let config = state.working_memory_config.read().await.clone();
        validate_working_memory_slot_id(&req.id, &config)?;
        let mut registry = state.working_memory_slots.write().await;
        let namespace = authority.namespace();
        registry.prune_namespace(namespace, state.working_memory_clock.now());
        let (existed, empty) =
            registry
                .namespaces
                .get_mut(&namespace)
                .map_or((false, false), |namespace_state| {
                    let existed = namespace_state.slots.remove(&req.id).is_some();
                    (existed, namespace_state.slots.is_empty())
                });
        if empty {
            registry.namespaces.remove(&namespace);
        }
        Ok(Json(serde_json::json!({"ok": true, "removed": existed})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:11009`. Registration: `akasha-daemon/src/main.rs:4390`.

<a id="post-v1-working-memory-slots-inject" />

## POST `/v1/working-memory/slots/inject` [#post-v1working-memoryslotsinject]

Working memory slots inject

| Availability         | Source contract                                                  |
| -------------------- | ---------------------------------------------------------------- |
| Registration         | `always registered`                                              |
| Runtime service      | No prefix-level service check; handler dependencies still apply. |
| Handler dependencies | See handler source and return expressions.                       |

**Access:** Daemon authentication and capability namespace authority; memory-domain permissions apply where mapped. Handler additionally checks require(CoreAction::Write, Some(request\_authority::MEMORY\_WORKING)); require\_matching\_db(\&db).

### Request [#request-5]

**Json** — `WmSlotInjectReq`

| Field   | Rust type           | Required on input | Notes |
| ------- | ------------------- | ----------------- | ----- |
| `id`    | `String`            | Yes               |       |
| `value` | `serde_json::Value` | Yes               |       |

```rust
struct WmSlotInjectReq {
    id: String,
    value: serde_json::Value,
}
```

### 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, "id": req.id})
```

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

Directly referenced error variants: `Internal`, `InvalidRequest`, `PayloadTooLarge`, `WorkingMemoryCapacity`. 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 working_memory_slots_inject(
        State(state): State<AppState>,
        Extension(db): Extension<Arc<AkashaDB>>,
        Extension(authority): Extension<RequestAuthority>,
        Json(req): Json<WmSlotInjectReq>,
    ) -> Result<impl IntoResponse, DaemonError> {
        state.record_http_request();
        authority.require(CoreAction::Write, Some(request_authority::MEMORY_WORKING))?;
        authority.require_matching_db(&db)?;
        let config = state.working_memory_config.read().await.clone();
        validate_working_memory_slot_id(&req.id, &config)?;
        let value_size = serde_json::to_vec(&req.value)
            .map_err(|error| DaemonError::InvalidRequest(error.to_string()))?
            .len();
        if value_size > config.max_value_bytes {
            return Err(DaemonError::PayloadTooLarge(format!(
                "working memory value exceeds {} bytes",
                config.max_value_bytes
            )));
        }
        let mut registry = state.working_memory_slots.write().await;
        let now = state.working_memory_clock.now();
        registry.prune_all(now);
        let namespace = authority.namespace();
        if !registry.namespaces.contains_key(&namespace)
            && registry.namespaces.len() >= config.max_namespace_entries
        {
            return Err(DaemonError::WorkingMemoryCapacity(
                "working memory namespace capacity exceeded".to_string(),
            ));
        }
        let namespace_state = registry.namespaces.entry(namespace).or_default();
        if namespace_state.slots.len() >= config.max_slots
            && !namespace_state.slots.contains_key(&req.id)
        {
            return Err(DaemonError::WorkingMemoryCapacity(
                "working memory namespace slot capacity exceeded".to_string(),
            ));
        }
        let expires_at = now
            .checked_add(std::time::Duration::from_secs(config.ttl_seconds))
            .ok_or_else(|| DaemonError::Internal("working memory expiry overflow".to_string()))?;
        namespace_state.slots.insert(
            req.id.clone(),
            WorkingMemorySlot {
                value: req.value,
                expires_at,
            },
        );
        Ok(Json(serde_json::json!({"ok": true, "id": req.id})))
    }
    ```
  </Accordion>
</Accordions>

Source: `akasha-daemon/src/main.rs:11043`. Registration: `akasha-daemon/src/main.rs:4394`.