Architecture

Workspace Layout

memoria/                          # Cargo workspace root
├── crates/
│   ├── memoria-core/             # Shared types: MemoriaError, Memory, MemoryType
│   ├── memoria-storage/          # SqlMemoryStore — all SQL queries, migrations
│   ├── memoria-service/          # Business logic
│   │   └── src/
│   │       ├── service.rs        # MemoryService — main entry point
│   │       ├── scheduler.rs      # GovernanceScheduler — periodic tasks + leader election
│   │       ├── config.rs         # Config struct (reads env vars)
│   │       ├── distributed.rs    # DistributedLock, AsyncTaskStore traits + SQL impls
│   │       ├── governance/       # GovernanceStrategy trait, DefaultGovernanceStrategy
│   │       └── plugin/           # Plugin system (manifest, repository, rhai, grpc)
│   ├── memoria-api/              # REST API (axum)
│   │   └── src/
│   │       ├── lib.rs            # build_router(), route registration
│   │       ├── state.rs          # AppState (service, task_store, instance_id)
│   │       └── routes/           # memory, admin, governance, plugins, sessions
│   ├── memoria-mcp/              # MCP server (stdio/SSE transport)
│   ├── memoria-cli/              # CLI binary: init, mcp, serve, plugin, benchmark
│   ├── memoria-embedding/        # Embedding + LLM client
│   └── memoria-git/              # Git-for-Data: snapshots, branches, merge
├── Cargo.toml                    # Workspace deps
└── build.rs                      # Proto compilation (tonic)

Key Traits

trait GovernanceStrategy: Send + Sync {
    fn strategy_key(&self) -> &str;
    async fn plan(&self, store, task) -> Result<GovernancePlan>;
    async fn execute(&self, store, task, plan) -> Result<GovernanceExecution>;
}

trait GovernanceStore: Send + Sync {
    async fn list_active_users(&self) -> Result<Vec<String>>;
    async fn quarantine_low_confidence(&self, user) -> Result<i64>;
    // ... cleanup/maintenance methods
}

trait DistributedLock: Send + Sync {
    async fn try_acquire(&self, key, holder, ttl) -> Result<bool>;
    async fn renew(&self, key, holder, ttl) -> Result<bool>;
    async fn release(&self, key, holder) -> Result<()>;
}

trait AsyncTaskStore: Send + Sync {
    async fn create_task(&self, task) -> Result<()>;
    async fn complete_task(&self, task_id, result) -> Result<()>;
    async fn fail_task(&self, task_id, error) -> Result<()>;
    async fn get_task(&self, task_id) -> Result<Option<AsyncTask>>;
}

Database Tables

Config

Config struct in config.rs reads from env vars:

When adding a Config field: update ALL test Config { .. } constructors — check scheduler.rs tests AND tests/plugin_repository.rs.

REST API Structure

Adding a New REST Endpoint

1. Add handler in memoria-api/src/routes/
2. Register route in memoria-api/src/lib.rs build_router()
3. Add e2e test in memoria-api/tests/api_e2e.rs using spawn_server()

Plugin System Files

plugin/
├── mod.rs              # Re-exports
├── manifest.rs         # PluginManifest, PluginPackage, signing verification
├── repository.rs       # Publish, review, score, binding rules, audit
├── rhai_runtime.rs     # RhaiGovernanceStrategy (sandboxed Rhai)
├── grpc_runtime.rs     # GrpcGovernanceStrategy (remote gRPC)
├── governance_hook.rs  # Contract testing harness
└── templates/          # Rhai governance template

Distributed Components

Testing

make check          # cargo check + clippy -D warnings (MUST pass)
make test-unit      # Unit tests (no DB): memoria-core, memoria-service, memoria-mcp
make test           # All tests (needs MatrixOne, --test-threads=1)
make test-e2e       # API e2e tests only

Patterns:

• E2e: spawn_server() → random port, shared DB, reqwest client
• Distributed e2e: spawn_server_with_instance() → custom instance ID
• Plugin: build_signed_plugin_files() helper for base64 file maps
• Unique names: uuid::Uuid::new_v4().simple() for test isolation
• DB tests need DATABASE_URL env var

Common Pitfalls

1. Adding Config fields → must update ALL test constructors
2. Clippy -D warnings → any warning = build failure
3. PathBuf::from("x") in comparisons → use Path::new("x")
4. format!() inside println!() → inline args directly
5. Plugin exports → re-export chain: repository.rs → plugin/mod.rs → lib.rs
6. Shared DB in tests → use unique names for isolation
7. GovernanceScheduler constructors → #[allow(clippy::too_many_arguments)]
8. MatrixOne DATETIME columns → use chrono::NaiveDateTime, not String