Database

Nehanda CLI persists all session state in a local SQLite database. You own this data — no cloud dependency for persistence. The database uses WAL (Write-Ahead Logging) mode for concurrent read performance.

Location

Database Characteristics

• WAL journal mode — readers don’t block writers, writers don’t block readers
• Foreign keys enabled
• Busy timeout 30 seconds (handles concurrent access)
• FTS5 full-text search index on the memories table
• Schema versioning via schema_meta table (current: v3)
• Jev-Mem graph — memories + memory_edges form a multi-relational graph (semantic / temporal / causal / entity edges) managed by the Laya System-1 control plane
• Pinned context — pinned_context table stores session-scoped invariants that survive compaction unchanged

Schema Reference

schema_meta

Key-value store for schema metadata.

conversations

One row per conversation. Tracks the active SDLC phase and project root.

sessions

One row per session (a session is a single runUserTurn invocation). Multiple sessions can belong to one conversation.

transcript_entries

The complete audit trail. Every user message, assistant response, tool call, and tool result is stored here as a sequence.

plans

SDLC plans created during the planning phase. Only approved plans are used.

events

SDLC milestones, subagent events, and task outputs.

state

Key-value store for per-conversation state (todos, worktree info, etc.).

memories + memories_fts

Long-term memory storage with full-text search. The FTS5 virtual table indexes title, content, keywords, and anticipated_queries using Porter stemming with Unicode 6.1 support.

This table is the canonical node store for the Jev-Mem memory architecture. Each row represents one observation (user turn, tool result, or assistant response) with overlapping type scores across four memory types.

memory_edges

Multi-relational graph edges for the Jev-Mem memory graph. The same node pair may have independent edges of different relation types.

laya_jev_state

System-1 canonical session control block. One row per session, updated on every turn by the Laya control plane.

pinned_context

Session-scoped domain invariants that survive context compaction unchanged. Used to persist ODSE schema mappings, asset capacity limits, simulation bounds, and other constants that must not be distilled or discarded during long sessions.

Unlike memories, pinned blocks are never passed to the distillation summariser. They are reattached verbatim at the start of every System-2 prompt, before the canonical Jev-Mem header and retrieved evidence.

(session_id, key) is unique — upserts replace existing content for the same key.

hook_invocations

Complete log of every hook execution. Every hook that fires (whether it matched, skipped, or ran) is recorded.

tool_permission_log

Every permission decision, regardless of outcome.

settings_snapshot

Effective settings after merge. Updated by /config commands and on bootstrap.

summaries

Conversation summaries for context compaction.

task_ratings

User ratings of task outcomes.

Useful Queries

Recent conversation turns

SELECT entry_type, 
       json_extract(payload_json, '$.content') AS preview,
       created_at
FROM transcript_entries
WHERE session_id = '<session-id>'
ORDER BY sequence DESC
LIMIT 20;

Tool calls in a session

SELECT json_extract(payload_json, '$.content[0].name') AS tool,
       json_extract(payload_json, '$.content[0].input') AS input,
       created_at
FROM transcript_entries
WHERE session_id = '<session-id>'
  AND entry_type = 'assistant'
  AND payload_json LIKE '%tool_use%'
ORDER BY sequence;

Permission audit

SELECT tool_name, decision, created_at
FROM tool_permission_log
ORDER BY created_at DESC
LIMIT 50;

Hook execution log

SELECT hook_event, matcher, command, exit_code, 
       substr(stdout_text, 1, 200) AS stdout_preview,
       skipped_reason
FROM hook_invocations
ORDER BY id DESC
LIMIT 50;

Full-text search memories

SELECT title, content, rank
FROM memories_fts
WHERE memories_fts MATCH 'error handling'
ORDER BY rank;