Skip to main content

​
Codebase Guide

​
Workspace Layout

Memorose is a Cargo workspace with four crates plus a Next.js dashboard: 
Memorose/
  crates/
    memorose-common/    # Shared types, config, serialization
    memorose-core/      # Core engine — storage, LLM, worker, graph
    memorose-server/    # Axum HTTP server, Raft consensus, dashboard auth
    memorose-gateway/   # Stateless gateway, tenant sharding
  dashboard/            # Next.js frontend (TypeScript / React)
  scripts/              # Dev helpers (start_cluster.sh, build_dashboard.sh)
  examples/             # SDK examples and integrations

​
Crate Dependency Graph

memorose-server ──┐
                  ├──→ memorose-core ──→ memorose-common
memorose-gateway ─┘
  • memorose-common has no internal dependencies — it is pure types and config.
  • memorose-core depends on memorose-common and contains all business logic.
  • memorose-server and memorose-gateway both depend on memorose-core and memorose-common.

​
Crate Responsibilities

​
memorose-common

Shared foundations used by every other crate:
  • Event, EventContent, Memory domain types
  • Configuration loading — TOML file + environment variable overrides
  • Serialization helpers (serde, chrono, uuid)
  • Error types (thiserror)

​
memorose-core

The bulk of the codebase. Key modules:
ModulePathRole
engine/src/engine/MemoroseEngine — main orchestrator with ~17 submodules for memory operations
storage/src/storage/Multi-backend abstraction (see below)
worker.rssrc/worker.rsBackground consolidation pipeline: L0 → L1 → L2, decay, pruning, community detection
llm/src/llm/LLM provider abstraction — Gemini, OpenAI, and Mock implementations
graph/src/graph/Knowledge graph operations, community detection (Louvain / LPA)
ingest/src/ingest/Event ingestion pipeline
raft/src/raft/Distributed consensus via openraft
fact_extraction.rssrc/fact_extraction.rsLLM-based fact extraction from raw events
arbitrator.rssrc/arbitrator.rsConflict resolution between overlapping memories
reranker.rssrc/reranker.rsSearch result reranking

​
Storage Backends

All under memorose-core/src/storage/:
FileBackendPurpose
kv.rsRocksDBKey-value store for L0 raw events
index.rsLanceDB + TantivyVector index (LanceDB) + full-text index (Tantivy) for L1 memories
graph.rsCustomKnowledge graph storage for L2 insights
blob.rsFile systemBlob storage for multimodal content
system_kv.rsRocksDBSystem metadata and internal state
tests.rs—Comprehensive storage test suite

​
memorose-server

The HTTP layer:
  • main.rs — Axum routes, Raft node bootstrap, API handlers
  • shard_manager.rs — Shard-to-node routing logic
  • types.rs — API request / response types
  • dashboard/ — Dashboard authentication and handler endpoints

​
memorose-gateway

A stateless HTTP proxy that sits in front of server nodes:
  • Routes requests to the correct shard based on user_id
  • Handles tenant isolation via URL path
  • No persistent state of its own

​
Dashboard Frontend

The dashboard/ directory is a standard Next.js app: 
dashboard/src/
  app/           # Next.js app router pages
  components/    # React components
  lib/
    api.ts       # API client — all calls go through fetchAPI() with Bearer auth
    hooks.ts     # SWR hooks for data fetching
    types.ts     # TypeScript type definitions
Patterns to follow:
  • All API calls go through fetchAPI() in lib/api.ts
  • Data fetching uses SWR hooks defined in lib/hooks.ts
  • Types mirror the Rust server types in lib/types.ts

​
Key Patterns

​
SQL Filter Builder

build_user_filter(user_id, app_id, extra) constructs SQL WHERE clauses for LanceDB queries. Used across vector search operations.

​
KV Scan

Key-value iteration uses kv.scan(b"u:") with key window filtering for :unit: or :event: segments.

​
Dashboard Cache

Dashboard API responses are cached with a 5-minute TTL via state.dashboard_cache (powered by moka). search_bitemporal() supports both valid-time and transaction-time queries, with optional agent_id filtering as the 7th parameter.