> **Status:** Published
> **Date:** 2026-09-12
> **Scope**: API Reference
> **Standard**: Memorio API Specification v5
>
---
# Introspection & Inspection - Memorio

> ✅ **Universal**: Works in Browser, Node.js, Deno, and Edge Workers

Introspection utilities let you programmatically discover, verify, and read the shape of the global `state` proxy. Essential for AI agents that need to check whether a path exists before writing, or enumerate available keys before reading.

---

## stateKeys()

Returns all top-level keys currently on the `state` proxy. Excludes internal properties.

```javascript
import { state, memorio } from 'memorio'

state.user = { name: 'Sara' }
state.counter = 42

memorio.stateKeys()   // ['user', 'counter']
```

---

## pathExists(path)

Checks whether a dotted path exists in state. Returns `true` if the path resolves to a non-undefined value.

```javascript
state.user = { name: 'Sara', profile: { age: 30 } }

memorio.pathExists('user')           // true
memorio.pathExists('user.name')      // true
memorio.pathExists('user.profile')   // true
memorio.pathExists('user.profile.age') // true
memorio.pathExists('user.age')       // false
memorio.pathExists('nonexistent')    // false
```

This is critical for AI agents: always check `pathExists` before writing to a nested path to avoid creating unintended intermediate objects.

---

## stateType(path)

Returns the runtime type of the value at a given state path.

```javascript
state.count = 42
state.name = 'Sara'
state.items = [1, 2, 3]

memorio.stateType('count')    // 'number'
memorio.stateType('name')     // 'string'
memorio.stateType('items')    // 'array'
memorio.stateType('missing')  // 'undefined'
```

---

## stateGet(path)

Returns the value at a dotted path, deep-cloned to prevent accidental mutation of state.

```javascript
state.user = { name: 'Sara', tags: ['admin'] }

const user = memorio.stateGet('user')   // { name: 'Sara', tags: ['admin'] }
user.name = 'Luigi'                      // mutates the clone, not state
state.user.name                         // still 'Sara'
```

---

## stateSchema()

Generates a full schema report of the current state tree - every path with its type and whether it's defined.

```javascript
state.user = { name: 'Sara', age: 30 }
state.theme = 'dark'

memorio.stateSchema()
// [
//   { path: 'user',      type: 'object', defined: true },
//   { path: 'user.name', type: 'string', defined: true },
//   { path: 'user.age',  type: 'number', defined: true },
//   { path: 'theme',     type: 'string', defined: true }
// ]
```

This is the **most useful for AI agents** - it gives a complete picture of what's in state and what types the values are, in a single call. Perfect for:
- Discovering available state before generating code
- Validating that expected paths exist
- Understanding the shape of nested objects

---

## Full API

| Method | Parameters | Returns | Description |
|--------|-----------|---------|-------------|
| `memorio.stateKeys()` | none | `string[]` | Top-level state keys |
| `memorio.pathExists(path)` | `string` | `boolean` | Whether a path resolves to a value |
| `memorio.stateType(path)` | `string` | `string` | Runtime type at path |
| `memorio.stateGet(path)` | `string` | `any` | Deep-cloned value at path |
| `memorio.stateSchema()` | none | `SchemaEntry[]` | Full state tree report |

---

## How It Works

All introspection functions read from the global `state` proxy via `deepRaw()` - the same function used internally by the state proxy to unwrap itself before storing. This ensures consistent, non-proxied values are returned.

- `pathExists` and `stateGet` split the path on `.` and traverse the state tree.
- `stateSchema` recursively walks the state object, collecting every path and its type.
- All returned values from `stateGet` and `snapshot` are deep clones (via JSON round-trip) to prevent accidental mutation.
