Codebase Guide

Workspace layout

Memorose is a Cargo workspace with four crates plus a Next.js dashboard:

Memorose/
  crates/
    memorose-common/    # Shared types and config loading
    memorose-core/      # Core engine, retrieval, storage, graph, worker logic
    memorose-server/    # Axum HTTP server and dashboard-backed API surface
    memorose-gateway/   # Stateless gateway for shard routing
  dashboard/            # Next.js frontend
  scripts/              # Local dev helpers
  examples/             # Example clients and integrations

Crate dependency graph

memorose-server ──┐
                  ├──→ memorose-core ──→ memorose-common
memorose-gateway ─┘

Crate responsibilities

memorose-common

Shared foundations used by the rest of the workspace:

core types such as Event, EventContent, MemoryUnit, GraphEdge, and L3Task
runtime config loading in src/config.rs
serialization helpers and shared enums

memorose-core

Business logic and storage orchestration:

Module	Path	Role
`engine/`	`src/engine/`	`MemoroseEngine` orchestration and domain workflows
`storage/`	`src/storage/`	RocksDB, vector, text, blob, and system metadata backends
`worker.rs`	`src/worker.rs`	background consolidation, forgetting, insights, and related cycles
`llm/`	`src/llm/`	Gemini and OpenAI provider clients
`graph/`	`src/graph/`	graph storage, traversal, cache, and query helpers
`ingest/`	`src/ingest/`	multimodal ingest helpers
`raft/`	`src/raft/`	openraft integration
`arbitrator.rs`	`src/arbitrator.rs`	memory conflict and correction planning
`reranker.rs`	`src/reranker.rs`	weighted or external reranking

Storage backends

All under memorose-core/src/storage/:

File	Backend	Purpose
`kv.rs`	RocksDB	durable key-value storage for events and memory units
`index.rs`	LanceDB + Tantivy	vector and text indexing
`graph.rs`	custom	graph edge persistence
`blob.rs`	file system	asset storage
`system_kv.rs`	RocksDB	internal metadata, jobs, and control state

memorose-server

The HTTP layer:

main.rs: route definitions and server bootstrap
types.rs: request / response payload types
shard_manager.rs: shard routing and cluster coordination helpers
dashboard/: auth and handler modules backing dashboard and management endpoints

memorose-gateway

The stateless routing layer used in some deployments:

maps requests to backend nodes by shard
reads gateway-specific env vars such as SHARD_COUNT
does not own persistent state

Dashboard frontend

The dashboard/ app currently contains:

dashboard/src/
  app/           # Next.js app router pages
  components/    # UI components
  lib/
    api.ts       # API helpers
    auth.ts      # auth helpers
    hooks.ts     # SWR hooks
    types.ts     # TypeScript API types

Useful patterns

Dashboard cache

Dashboard API responses are cached with state.dashboard_cache.

Bitemporal and scoped retrieval

Retrieval supports valid-time, transaction-time, org_id, and agent_id inputs through the server request payloads.

Route truth

When in doubt, treat these as the primary references:

crates/memorose-server/src/main.rs
crates/memorose-server/src/types.rs
crates/memorose-common/src/config.rs

​Codebase Guide

​Workspace layout

​Crate dependency graph

​Crate responsibilities

​memorose-common

​memorose-core

​Storage backends

​memorose-server

​memorose-gateway

​Dashboard frontend

​Useful patterns

​Dashboard cache

​Bitemporal and scoped retrieval

​Route truth