Development Setup

Set up your local development environment for Cerememory development.

Prerequisites

Rust 1.95+ -- Install via rustup. The workspace pins this MSRV via rust-toolchain.toml and CI enforces it.
Protobuf compiler (protoc) -- Required for gRPC code generation

Clone and Build

bash

git clone https://github.com/co-r-e/cerememory.git
cd cerememory
cargo build

The first build downloads and compiles all dependencies. Subsequent incremental builds are fast.

Running Tests

All Tests

bash

cargo test

Specific Crate

bash

cargo test -p cerememory-decay
cargo test -p cerememory-core
cargo test -p cerememory-transport-http

Integration Tests

bash

cargo test -p integration

With Output

bash

cargo test -- --nocapture

Linting and Formatting

Format Check

bash

cargo fmt --check

Format Fix

bash

cargo fmt

Clippy

bash

cargo clippy --all-targets --all-features -- -D warnings

Development Workflow

Running the Server Locally

bash

cargo run -p cerememory-cli -- serve --port 8420

With an LLM provider:

bash

CEREMEMORY_LLM__PROVIDER=claude \
CEREMEMORY_LLM__API_KEY=sk-ant-... \
cargo run -p cerememory-cli -- serve

Testing with curl

bash

# Store a memory
curl -X POST http://localhost:8420/v1/encode \
  -H "Content-Type: application/json" \
  -d '{"content":{"blocks":[{"modality":"text","format":"text/plain","data":[72,101,108,108,111]}]},"store":"episodic"}'
 
# Check stats
curl http://localhost:8420/v1/introspect/stats
 
# Health check
curl http://localhost:8420/health

Running Benchmarks

bash

cargo bench -p cerememory-decay

Project Structure

Key directories for development:

Path	Purpose
`crates/cerememory-core/`	Types, traits, protocol -- start here for data model changes
`crates/cerememory-engine/`	Central engine -- start here for behavior changes
`crates/cerememory-decay/`	Decay math and engine -- isolated, easy to test
`crates/cerememory-transport-http/`	HTTP endpoints -- start here for API changes
`crates/cerememory-config/`	Configuration loading and validation
`crates/cerememory-store-*/`	Individual store implementations
`adapters/adapter-*/`	LLM provider adapters
`tests/integration/`	End-to-end integration tests

Adding a New Store Operation

Define the protocol types in cerememory-core/src/protocol.rs -- add request and response structs.

Add the trait method to cerememory-core/src/traits.rs if the operation involves a new store capability.

Implement in the engine in cerememory-engine/src/lib.rs.

Add the HTTP handler in cerememory-transport-http/src/lib.rs -- add the route and handler function.

Add the CLI command in cerememory-cli/src/main.rs -- add a new variant to the Commands enum.

Write tests at each layer: unit tests in the crate, integration tests in tests/integration.

Adding a New LLM Adapter

Create a new crate under adapters/adapter-<name>/
Implement the LLMProvider trait from cerememory-core
Add the crate to the workspace Cargo.toml
Add a feature flag to cerememory-cli (e.g., llm-<name>)
Wire the provider in cerememory-cli/src/main.rs under build_llm_provider()

Debugging Tips

Enable Trace Logging

bash

RUST_LOG=cerememory_engine=trace cargo run -p cerememory-cli -- serve

Per-Crate Logging

bash

RUST_LOG=cerememory_decay=debug,cerememory_transport_http=trace cargo run -p cerememory-cli -- serve

JSON Log Format

For structured logging (useful with log aggregation tools):

bash

CEREMEMORY_LOG__FORMAT=json cargo run -p cerememory-cli -- serve

Next Steps

Contributing Guide

PR process, commit conventions, and code style

Architecture

Understand the system architecture