Developing Berry¶

This guide covers setting up a local development environment for the Berry project.

Prerequisites¶

• Rust 1.75+ (install via rustup)
• Docker (optional, only needed for ChromaDB or integration tests)

Setup¶

# Clone the repository
git clone https://github.com/geoffjay/berry-rs.git
cd berry

# Build all packages
cargo build

# Run tests
cargo test --all

Running the Services¶

Berry uses LanceDB by default (embedded, no setup needed). You only need to run the Berry server.

If you want to use ChromaDB instead, start it first:

docker run -d -p 8000:8000 chromadb/chroma

Start Berry Server¶

In development mode (with debug logging):

BERRY_LOG=debug cargo run -p berry-server -- --port 4114

Or build and run the release binary:

cargo build --release
./target/release/berry-server --port 4114

CLI Development¶

Configuration¶

Create ~/.config/berry/config.jsonc:

{
  "store": "lance",
  "server": {
    "url": "http://localhost:4114",
    "timeout": 5000
  },
  "defaults": {
    "type": "information",
    "createdBy": "user"
  },
  "lance": {
    "table": "berry_memories"
  }
}

Running the CLI¶

During development:

cargo run -p berry-cli -- --help
cargo run -p berry-cli -- remember "test memory"
cargo run -p berry-cli -- search "test"

Or build and use directly:

cargo build
./target/debug/berry --help

Testing Commands¶

# Store a memory
cargo run -p berry-cli -- remember "The API uses JWT tokens"

# Search memories
cargo run -p berry-cli -- search "authentication"

# Recall by ID
cargo run -p berry-cli -- recall mem_1234567890_abcdef

# Delete a memory
cargo run -p berry-cli -- forget mem_1234567890_abcdef

Building¶

Debug Build¶

cargo build

Binaries are placed in target/debug/: - target/debug/berry - target/debug/berry-server - target/debug/berry-mcp

Release Build¶

cargo build --release

Binaries are placed in target/release/.

Running Tests¶

# Run all tests
cargo test --all

# Run tests for a specific crate
cargo test -p berry

# Run tests with output
cargo test --all -- --nocapture

Code Formatting¶

cargo fmt --all

Linting¶

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

Adding New Features¶

Adding a New Memory Field¶

1. Update the Memory struct in crates/berry/src/types/memory.rs
2. Update CreateMemoryRequest in crates/berry/src/types/requests.rs
3. Update the ChromaDB metadata conversion in crates/berry/src/store/chroma.rs
4. Add CLI flags in crates/cli/src/main.rs
5. Update server routes as needed

Adding a New CLI Command¶

1. Create a new module in crates/cli/src/commands/
2. Export the module in crates/cli/src/commands/mod.rs
3. Add the subcommand to the Commands enum in crates/cli/src/main.rs
4. Handle the command in the main match statement

Adding a New API Endpoint¶

1. Create a handler in crates/server/src/routes/
2. Export the handler in crates/server/src/routes/mod.rs
3. Add the route in crates/server/src/main.rs

Debugging¶

Enable Debug Logging¶

BERRY_LOG=debug cargo run -p berry-server -- --port 4114

Available log levels: error, warn, info, debug, trace

JSON Log Format¶

BERRY_LOG_FORMAT=json cargo run -p berry-server -- --port 4114

Testing ChromaDB Connection¶

curl http://localhost:8000/api/v1/heartbeat

Testing Server Health¶

curl http://localhost:4114/health

Contributing¶

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: cargo test --all
5. Run clippy: cargo clippy --all-targets
6. Format code: cargo fmt --all
7. Submit a pull request

Troubleshooting¶

Cargo build fails with "edition 2024"¶

Ensure you have Rust 1.75+ installed:

rustup update stable

ChromaDB connection refused (if using ChromaDB)¶

Ensure ChromaDB is running:

docker ps | grep chroma

Start it if needed:

docker run -d -p 8000:8000 chromadb/chroma

Tests fail with network errors¶

Some integration tests may require external services (ChromaDB, Ollama) to be running. Tests that require external services should be marked appropriately.