ADR-0002: Three-Layer Storage Architecture

Status

Accepted

Context

Background and Problem Statement

Subcog requires storage capabilities that span three fundamentally different domains: durable persistence of memory records, fast full-text search for keyword-based retrieval, and high-dimensional vector similarity search for semantic retrieval. Each of these domains has distinct performance characteristics, failure modes, scaling patterns, and operational requirements. The architectural question is whether to implement these capabilities as a single unified storage system or as separate, composable layers.

The Three Storage Capabilities

The memory system requires three distinct storage capabilities:

Persistence Layer: The authoritative, durable storage for memory records. This layer must guarantee that once a memory is captured, it survives process restarts, system reboots, and storage media failures (through backups). The persistence layer is the single source of truth for all memory data, including content, metadata, timestamps, and relationships.
Index Layer: Fast metadata and full-text search capabilities using algorithms like BM25. This layer enables keyword-based retrieval where users search for memories containing specific terms. The index layer must support tokenization, stemming, and relevance ranking to surface the most pertinent memories for a given query.
Vector Layer: High-dimensional embedding storage and approximate nearest neighbor (ANN) search. This layer enables semantic retrieval where memories are found based on meaning rather than exact keyword matches. The vector layer stores dense floating-point vectors (typically 384 dimensions for MiniLM-L6-v2) and performs similarity searches using algorithms like HNSW (Hierarchical Navigable Small World graphs).

The Coupling Problem with Monolithic Storage

A monolithic approach that combines all three capabilities in a single storage system creates tight coupling that severely limits deployment flexibility and operational resilience:

+-------------------------------------------------------------------+
|                    MONOLITHIC STORAGE                             |
+-------------------------------------------------------------------+
|  Persistence + Index + Vector all in one system                   |
+-------------------------------------------------------------------+
|                                                                   |
|  Problems:                                                        |
|  +------------------+  +------------------+  +------------------+ |
|  | Can't use        |  | Single point     |  | Scaling limited  | |
|  | SQLite locally   |  | of failure       |  | by weakest       | |
|  | + Postgres in    |  | for all ops      |  | component        | |
|  | production       |  |                  |  |                  | |
|  +------------------+  +------------------+  +------------------+ |
|                                                                   |
|  +------------------+  +------------------+  +------------------+ |
|  | Vector index     |  | Full-text and    |  | Testing          | |
|  | rebuild blocks   |  | vector queries   |  | requires full    | |
|  | all operations   |  | compete for      |  | infrastructure   | |
|  |                  |  | resources        |  |                  | |
|  +------------------+  +------------------+  +------------------+ |
|                                                                   |
+-------------------------------------------------------------------+

Specific problems with the monolithic approach include:

Deployment Inflexibility: A monolithic system forces the same storage technology for all environments. Developers working locally would need the same PostgreSQL+pgvector setup as production, creating friction for onboarding and development. The three-layer approach allows SQLite locally (zero configuration) while using PostgreSQL in production (multi-user, scalable).
Single Point of Failure: If the monolithic storage system experiences issues (database corruption, connection pool exhaustion, disk full), all three capabilities fail simultaneously. With separate layers, the persistence layer can continue accepting writes even if the vector index is temporarily unavailable for rebuilding.
Resource Contention: Full-text search queries (I/O bound, seeks into inverted indices) and vector similarity searches (CPU bound, distance calculations) have fundamentally different resource profiles. In a monolithic system, these compete for the same connection pool and memory resources, leading to unpredictable performance under mixed workloads.
Scaling Constraints: Each layer has different scaling characteristics. The persistence layer scales with storage capacity (disk space), the index layer scales with query throughput (read replicas), and the vector layer scales with index memory (RAM for HNSW graphs). A monolithic system must scale all dimensions together, leading to over-provisioning.
Rebuild and Maintenance Operations: Rebuilding a vector index (necessary when changing embedding models or adding dimensions) in a monolithic system would block all storage operations. With separate layers, the vector layer can be rebuilt from the persistence layer without affecting search or write operations.
Testing Complexity: Unit and integration tests for a monolithic storage system require the full infrastructure. Separate layers enable mocking individual backends, making tests faster and more focused.

Layer Separation Rationale

Each layer has fundamentally different operational characteristics that justify separation:

Aspect	Persistence Layer	Index Layer	Vector Layer
Primary Function	Durable record storage	Keyword search	Semantic similarity search
Data Model	Structured records (JSON/relational)	Inverted index (term -> doc IDs)	Dense vectors (float arrays)
Failure Mode	Data loss is catastrophic and unrecoverable	Rebuildable from persistence layer	Rebuildable from persistence layer
Consistency Requirement	Strong (ACID transactions)	Eventual acceptable	Eventual acceptable
Scaling Dimension	Storage capacity (disk)	Query throughput (read replicas)	Index memory (RAM)
Deployment Requirement	Must be highly available and durable	Can be ephemeral with rebuild capability	Can be ephemeral with rebuild capability
Update Pattern	Write-heavy (captures, updates)	Read-heavy (searches far exceed writes)	Batch updates (embedding generation is expensive)
Latency Budget	10-50ms acceptable for writes	Less than 5ms required for search	Less than 10ms required for search
Resource Profile	I/O bound (disk writes, fsync)	I/O bound (index seeks)	CPU bound (distance calculations)

This separation enables critical operational patterns:

Graceful Degradation: If the vector layer is unavailable (rebuilding, out of memory), the system can fall back to keyword search via the index layer. If the index layer is unavailable, users can still capture memories (persistence works) and retrieve by ID.
Independent Optimization: Each layer can be tuned for its specific workload. The persistence layer can use WAL mode with synchronous commits for durability. The index layer can use aggressive caching for read performance. The vector layer can trade accuracy for speed using HNSW parameters.
Flexible Deployment Topologies: Local development uses SQLite for all three layers (single file, zero configuration). Team deployments can use PostgreSQL for persistence and index with Redis for distributed vector search. Enterprise deployments can use PostgreSQL+pgvector with read replicas.
Simplified Testing: Each layer can be tested independently with mock implementations. Integration tests can substitute in-memory backends for faster execution.
Technology Evolution: As new storage technologies emerge (e.g., native vector databases, new full-text engines), individual layers can be swapped without rewriting the entire system.

Decision Drivers

Primary Decision Drivers

The following factors were weighted most heavily in the storage architecture decision:

Deployment Flexibility Requirement: The system must support both single-developer local usage (zero external dependencies, single-file database) and team/enterprise deployments (multi-user, scalable, centralized). A monolithic architecture cannot satisfy both requirements without significant complexity.
Rebuild Resilience Requirement: Vector embeddings may need to be regenerated when changing embedding models or dimensions. The architecture must support rebuilding derived indices (index and vector layers) from the authoritative persistence layer without data loss or extended downtime.
Failure Isolation Requirement: A failure in one storage capability (e.g., vector index corruption) must not cascade to affect other capabilities. Users must be able to continue capturing memories even if search is degraded.
Performance Isolation Requirement: Different storage operations have different resource profiles and latency requirements. The architecture must prevent resource contention between write-heavy persistence operations and read-heavy search operations.
Testability Requirement: The storage layer must be testable without requiring full infrastructure. Unit tests should be able to mock individual backends, and integration tests should run with lightweight in-memory implementations.

Secondary Decision Drivers

The following factors influenced the decision but were not individually decisive:

Rust Trait System Fit: Rust's trait system provides an ergonomic way to define backend interfaces with compile-time polymorphism. The trait PersistenceBackend, trait IndexBackend, and trait VectorBackend abstractions map naturally to Rust's type system.
Ecosystem Compatibility: The Rust ecosystem provides high-quality crates for each backend type (rusqlite, tokio-postgres, redis-rs, usearch), making the three-layer architecture straightforward to implement.
Operational Observability: Separate layers enable per-layer metrics, making it easier to identify performance bottlenecks and capacity issues.

Considered Options

Option 1: Three Independent Pluggable Layers (Selected)

Description: Implement storage as three independent layers with trait-based abstractions. Each layer has multiple backend implementations that can be mixed and matched based on deployment requirements.

Architecture:

// Persistence layer trait - authoritative storage
pub trait PersistenceBackend: Send + Sync {
    fn store(&self, memory: &Memory) -> Result<()>;
    fn get(&self, id: &MemoryId) -> Result<Option<Memory>>;
    fn delete(&self, id: &MemoryId) -> Result<bool>;
    fn list_ids(&self) -> Result<Vec<MemoryId>>;
    fn get_batch(&self, ids: &[MemoryId]) -> Result<Vec<Memory>>;
    fn exists(&self, id: &MemoryId) -> Result<bool>;
    fn count(&self) -> Result<usize>;
}

// Index layer trait - full-text search
pub trait IndexBackend: Send + Sync {
    fn index(&self, memory: &Memory) -> Result<()>;
    fn remove(&self, id: &MemoryId) -> Result<bool>;
    fn search(&self, query: &str, filter: &SearchFilter, limit: usize)
        -> Result<Vec<(MemoryId, f32)>>;
    fn reindex(&self, memories: &[Memory]) -> Result<()>;
    fn clear(&self) -> Result<()>;
    fn list_all(&self, filter: &SearchFilter, limit: usize)
        -> Result<Vec<(MemoryId, f32)>>;
    fn get_memory(&self, id: &MemoryId) -> Result<Option<Memory>>;
    fn get_memories_batch(&self, ids: &[MemoryId]) -> Result<Vec<Option<Memory>>>;
}

// Vector layer trait - similarity search
pub trait VectorBackend: Send + Sync {
    fn dimensions(&self) -> usize;
    fn upsert(&self, id: &MemoryId, embedding: &[f32]) -> Result<()>;
    fn remove(&self, id: &MemoryId) -> Result<bool>;
    fn search(&self, query_embedding: &[f32], filter: &VectorFilter, limit: usize)
        -> Result<Vec<(MemoryId, f32)>>;
    fn count(&self) -> Result<usize>;
    fn clear(&self) -> Result<()>;
}

Available Backend Implementations:

Layer	Backend	Use Case	Configuration
Persistence	`SqliteBackend`	Local development, single-user	Default, embedded
Persistence	`PostgresBackend`	Multi-user, team deployments	Requires PostgreSQL server
Persistence	`FilesystemBackend`	Fallback, simple deployments	JSON files on disk
Index	`SqliteFts5Backend`	Local development	Default, uses FTS5 extension
Index	`PostgresTsBackend`	Multi-user deployments	Uses PostgreSQL full-text search
Index	`RediSearchBackend`	High-throughput deployments	Requires Redis with RediSearch module
Vector	`UsearchBackend`	Local development	Default, in-process HNSW
Vector	`PgVectorBackend`	Multi-user deployments	Requires PostgreSQL with pgvector extension
Vector	`RedisVectorBackend`	Distributed deployments	Requires Redis Stack with vector search

Advantages:

Maximum deployment flexibility (SQLite locally, PostgreSQL in production)
Failure isolation between layers
Independent scaling of each layer
Rebuild capability without data loss
Clean separation of concerns
Testable with mock implementations
Future backends can be added without code changes

Disadvantages:

More complex architecture with three layers to coordinate
Cross-layer coordination overhead for operations spanning multiple layers
Potential consistency challenges between layers (addressed by treating persistence as authoritative)
Configuration complexity for deployment

Risk Assessment:

Technical Risk: Low. Trait-based abstractions are well-understood patterns.
Operational Risk: Medium. Requires coordination between layers for consistency.
Complexity Risk: Medium. Three separate systems to configure and monitor.

Option 2: PostgreSQL-Only Monolith

Description: Use PostgreSQL with extensions (pgvector for vectors, built-in full-text search) as a single storage system for all capabilities.

Advantages:

Single database to manage
ACID transactions across all operations
Mature, well-understood technology
Strong ecosystem and tooling

Disadvantages:

Requires PostgreSQL server for all deployments, including local development
Single point of failure for all storage operations
Cannot use SQLite for zero-configuration local development
Resource contention between different query types
Scaling requires PostgreSQL-specific solutions (read replicas, sharding)
Vector index rebuild affects all operations

Disqualifying Factor: The requirement for zero-configuration local development (single-file database, no server installation) cannot be satisfied with PostgreSQL. Developers should not need to install and configure a database server to use Subcog locally.

Option 3: SQLite-Only Monolith

Description: Use SQLite with extensions (FTS5 for full-text, custom vector table for embeddings) as a single storage system.

Advantages:

Zero-configuration deployment
Single-file database, easy to backup and restore
No external dependencies
Well-suited for single-user local development

Disadvantages:

Single-process access limitation prevents multi-user deployments
No built-in vector search capability (would require custom implementation)
Cannot scale to team/enterprise deployments
Limited concurrency (single writer, multiple readers with WAL)
Not suitable for distributed deployments

Disqualifying Factor: The single-process access limitation and lack of native vector search make SQLite unsuitable as the only storage option. Team deployments require multi-user concurrent access that SQLite cannot provide.

Option 4: Two-Layer Architecture (Persistence + Combined Search)

Description: Separate persistence from search, but combine full-text and vector search into a single search layer.

Advantages:

Simpler than three layers
Persistence isolation maintained
Search operations coordinated within single layer

Disadvantages:

Full-text and vector search have different backend requirements
Limits backend choices (need systems that support both)
Resource contention within search layer
Scaling constraints (must scale both search types together)

Disqualifying Factor: Combining full-text and vector search into a single layer limits backend choices. For example, Redis RediSearch excels at full-text search, while usearch excels at vector search. The combined layer would force a lowest-common-denominator backend or complex hybrid implementations.

Decision

We will implement storage as three independent, pluggable layers with trait-based abstractions. Each layer will have multiple backend implementations that can be configured independently.

Layer Specifications

Persistence Layer (PersistenceBackend trait):

The persistence layer is the authoritative source of truth for all memory records. Key characteristics:

Consistency Model: Strong consistency with ACID transactions (where supported)
Durability Guarantee: Memories survive process restarts and system reboots
Transactional Behavior:
- SQLite: Full ACID with WAL mode, serializable isolation, durability on commit
- PostgreSQL: Full ACID with configurable isolation levels
- Filesystem: No transactional guarantees (fsync for durability)
Error Recovery: Retry with exponential backoff for transient errors

Index Layer (IndexBackend trait):

The index layer provides full-text search using BM25 or similar algorithms. Key characteristics:

Consistency Model: Derived from persistence layer; eventual consistency acceptable
Rebuild Capability: Can be fully rebuilt from persistence layer data
Performance Target: Less than 5ms search latency for typical queries
Tokenization: Whitespace and punctuation split (SQLite), language-aware stemming (PostgreSQL)

Vector Layer (VectorBackend trait):

The vector layer provides semantic similarity search using embedding vectors. Key characteristics:

Consistency Model: Derived from persistence layer; eventual consistency acceptable
Rebuild Capability: Can be fully rebuilt by re-embedding content from persistence layer
Performance Target: Less than 10ms search latency for typical queries
Dimensionality: 384 dimensions (MiniLM-L6-v2) by default, configurable
Algorithm: HNSW (Hierarchical Navigable Small World) for approximate nearest neighbor search

Composite Storage

The CompositeStorage struct combines all three layers:

pub struct CompositeStorage<P, I, V>
where
    P: PersistenceBackend,
    I: IndexBackend,
    V: VectorBackend,
{
    persistence: P,
    index: I,
    vector: V,
}

This enables compile-time verification that all three layers are configured and type-safe access to each layer.

Layer Interaction

Write Path (Memory Capture)

When a memory is captured, the write path ensures durability first, then updates derived indices:

capture_memory(content, metadata)
        |
        v
+-------+-------+
|   PERSISTENCE |  Step 1: Store authoritative record
|   (SQLite)    |     - Generate UUID v7 (time-sortable)
|               |     - Write content + metadata + timestamps
+-------+-------+     - Return memory_id
        |             - Latency: ~5ms
        |
        | memory_id, content
        v
+-------+-------+
|     INDEX     |  Step 2: Update full-text search index
|   (FTS5)      |     - Tokenize content (whitespace, punctuation)
|               |     - Insert into inverted index
+-------+-------+     - Latency: ~2ms
        |
        | memory_id, content
        v
+-------+-------+
|    VECTOR     |  Step 3: Generate and store embedding
|   (usearch)   |     - Generate embedding via fastembed (~50ms)
+---------------+     - Insert into HNSW index (~1ms)
                      - Latency: ~51ms

Total write latency: ~58ms (dominated by embedding generation)

Write Path Guarantees:

Persistence write is completed before index/vector updates begin
If index or vector updates fail, the memory is still persisted (eventual consistency)
Subsequent searches will find the memory once indices catch up

Read Path (Hybrid Search)

When searching for memories, the read path executes full-text and vector searches in parallel, then fuses results:

search_memories(query, limit=10)
        |
        +------------------+------------------+
        |                  |                  |
        v                  v                  v
+-------+-------+  +-------+-------+  +-------+-------+
| EMBEDDING GEN |  |     INDEX     |  |    VECTOR     |
|  (fastembed)  |  |   (FTS5)      |  |   (usearch)   |
+---------------+  +---------------+  +---------------+
| Generate query|  | BM25 search   |  | (waits for    |
| embedding     |  | Return top-k  |  |  embedding)   |
| ~50ms         |  | with scores   |  | KNN search    |
+-------+-------+  | ~2ms          |  | ~5ms          |
        |          +-------+-------+  +-------+-------+
        |                  |                  |
        +------------------+                  |
                           |                  |
                           | ranked_ids[]     | ranked_ids[]
                           |                  |
                           +--------+---------+
                                    |
                                    v
                            +-------+-------+
                            |  RRF FUSION   |
                            +---------------+
                            | Reciprocal    |
                            | Rank Fusion   |
                            | k=60          |
                            +-------+-------+
                                    |
                                    | final_ids[]
                                    v
                            +-------+-------+
                            |  PERSISTENCE  |
                            |   (SQLite)    |
                            +---------------+
                            | Batch fetch   |
                            | full records  |
                            | ~3ms          |
                            +---------------+

Total search latency: ~60ms (dominated by embedding generation)
Cached embedding: ~10ms

Reciprocal Rank Fusion (RRF):

RRF combines rankings from multiple retrieval methods using the formula:

RRF_score(d) = sum(1 / (k + rank_i(d))) for each retrieval method i

Where:

d is a document (memory)
k is a constant (default: 60) that controls the influence of high vs. low rankings
rank_i(d) is the rank of document d in retrieval method i (1-indexed)

This fusion method:

Does not require score normalization between methods
Handles cases where a document appears in only one ranking
Empirically shown to outperform individual methods and simple score averaging

Rebuild Path (Index/Vector Reconstruction)

When indices need to be rebuilt (e.g., embedding model change, index corruption):

rebuild_indices()
        |
        v
+-------+-------+
|   PERSISTENCE |  Step 1: List all memory IDs
+-------+-------+
        |
        | memory_ids[]
        v
+-------+-------+
|   PERSISTENCE |  Step 2: Batch fetch memories
+-------+-------+     (avoid N+1 queries)
        |
        | memories[]
        v
+-------+-------+
|     INDEX     |  Step 3: Clear and reindex
|   (FTS5)      |     - Clear existing index
+-------+-------+     - Reindex all memories
        |             - Latency: O(n) where n = memory count
        |
        | memories[]
        v
+-------+-------+
|    VECTOR     |  Step 4: Clear and re-embed
|   (usearch)   |     - Clear existing index
+---------------+     - Generate embeddings (parallelized)
                      - Insert into HNSW
                      - Latency: O(n * embedding_time)

Consequences

Positive Consequences

Backend Selection via Configuration: Deployment topology is determined by configuration files, not code changes. The same binary works for local development (SQLite everywhere) and production (PostgreSQL + Redis).
Mix-and-Match Deployment Options: Different layers can use different backends based on requirements. For example:
- Local: SQLite persistence + SQLite FTS5 index + usearch vector
- Team: PostgreSQL persistence + PostgreSQL full-text index + pgvector
- Enterprise: PostgreSQL persistence + RediSearch index + Redis vector
Independent Scaling of Each Layer: Each layer can be scaled according to its specific bottleneck:
- Persistence: Add storage capacity, use connection pooling
- Index: Add read replicas, increase cache size
- Vector: Increase memory for HNSW, shard across nodes
Easier Testing with Mock Implementations: Unit tests can use in-memory mock implementations of each backend trait. Integration tests can use SQLite (fast, embedded) regardless of production backend choice.
Future Backends Without Code Changes: New backend implementations (e.g., DuckDB, Milvus, Qdrant) can be added by implementing the appropriate trait without modifying existing code.
Failure Isolation: A failure in one layer does not cascade to others:
- Vector layer down: Fall back to keyword search only
- Index layer down: Can still capture memories and retrieve by ID
- Persistence layer down: System is unavailable (acceptable for authoritative store)
Graceful Degradation: The system can operate with reduced functionality when layers are unavailable, rather than failing completely.

Negative Consequences

Increased Architectural Complexity: Three separate layers with trait abstractions add cognitive load for developers. The interaction patterns between layers must be well-documented and understood.
Cross-Layer Coordination Overhead: Operations that span multiple layers (capture, search) require coordination. The write path must update three layers, and the read path must query two layers and fuse results.
Potential Consistency Challenges: The index and vector layers are eventually consistent with the persistence layer. A memory captured but not yet indexed will not appear in search results. This is mitigated by:
- Treating persistence as the authoritative source
- Returning the captured memory directly from capture operations ("read your writes")
- Documenting expected propagation delays
Configuration Complexity: Deployments must configure three separate backends, each with their own connection strings, credentials, and tuning parameters. This is mitigated by sensible defaults (SQLite for all layers by default).
Monitoring Overhead: Three separate layers require three sets of metrics, alerts, and dashboards. Each layer may have different failure modes requiring different operational responses.

Neutral Consequences

Trait-Based Abstraction Overhead: Using dynamic dispatch (dyn Trait) for backend polymorphism adds a small runtime cost (vtable lookup). Static dispatch via generics is used where possible to minimize this overhead.
Backend Feature Parity: Different backends may have slightly different capabilities (e.g., PostgreSQL supports advanced full-text features that SQLite FTS5 does not). The trait abstraction exposes the common subset.

Decision Outcome

The three-layer architecture provides the flexibility to support both zero-configuration local development (SQLite for all layers) and scalable team/enterprise deployments (PostgreSQL, Redis) using the same codebase. The complexity of coordinating three layers is justified by:

The deployment flexibility requirement (local vs. team vs. enterprise)
The failure isolation benefits (graceful degradation)
The rebuild capability (regenerate indices without data loss)
The independent scaling capability (tune each layer for its workload)

The trait-based abstractions map naturally to Rust's type system and enable compile-time verification of backend configurations.

Related Decisions

ADR-0001: Rust as Implementation Language - Rust's trait system enables the pluggable backend architecture
ADR-0003: Feature Tier System - Feature tiers determine which backends are required
ADR-0047: Remove Git-Notes Storage Layer - SQLite replaces git-notes as primary persistence

Implementation Notes

Backend Trait Requirements

All backend traits require Send + Sync bounds for thread-safe usage across async tasks:

pub trait PersistenceBackend: Send + Sync { /* ... */ }
pub trait IndexBackend: Send + Sync { /* ... */ }
pub trait VectorBackend: Send + Sync { /* ... */ }

Backend implementations use interior mutability (e.g., Mutex<Connection>) for mutable state while satisfying the &self receiver requirement.

Batch Operations

All backends provide batch retrieval methods to avoid N+1 query patterns:

PersistenceBackend::get_batch(&[MemoryId]) -> Result<Vec<Memory>>
IndexBackend::get_memories_batch(&[MemoryId]) -> Result<Vec<Option<Memory>>>

These methods should be implemented with optimized queries (e.g., SQL IN clause) rather than looping over individual gets.

Error Handling

Backends return Result<T> with errors propagated via the crate's Error type. Common error variants:

Error::Storage - Backend-specific storage errors (connection failed, query error)
Error::NotFound - Requested resource does not exist
Error::InvalidInput - Input validation failed
Error::OperationFailed - Operation failed for unspecified reason

Links

rusqlite crate - SQLite bindings with FTS5 support
tokio-postgres crate - Async PostgreSQL client
usearch crate - HNSW vector search
Reciprocal Rank Fusion paper - RRF algorithm

More Information

Date: 2025-12-28
Source: SPEC-2025-12-28: Subcog Rust Rewrite

Audit

2026-01-04

Status: Compliant

Findings:

Finding	Files	Lines	Assessment
Persistence/index/vector layers and composite storage defined	`src/storage/mod.rs`	L1-L76	compliant
Persistence trait with required methods	`src/storage/traits/persistence.rs`	L1-L125	compliant
Index trait with BM25 search	`src/storage/traits/index.rs`	L1-L143	compliant
Vector trait with similarity search	`src/storage/traits/vector.rs`	L1-L215	compliant

Summary: Storage module documents and implements the three-layer abstraction with trait-based backends.

Action Required: None

`/`	Focus search
`Esc`	Clear search / Close panel
`j` / `↓`	Next item
`k` / `↑`	Previous item
`Enter`	Open selected
`1-4`	Switch view modes
`?`	Show this help

Keyboard Shortcuts