The Epistemic Me server is a Go-based backend service that provides belief and dialectic management capabilities through a gRPC interface.

• Go 1.21 or later
• Protocol Buffers compiler (protoc)
• OpenAI API key for AI-powered features
• Docker for containerization
• Docker Compose v2.22.0 or later for local development (required for watch/hotreload mode)

1. Install the Protocol Buffers compiler and Go plugins:

brew install protobuf
brew install protoc-gen-go
brew install protoc-gen-go-grpc
brew install protoc-gen-connect-go

2. Initialize the git submodules (proto):

git submodule init && git submodule update

1. Set your OpenAI API key in an .env file at the Epistemic Me project root(should be in a directory above the Server folder) with the following:

OPENAI_API_KEY=your_api_key_here

2. Start the development server with hot reload:

# Using Docker Compose v2.22.0+ with watch mode
docker compose up --watch

# For older Docker Compose versions, use:
docker compose up

1. Set your OpenAI API key in an .env file at the Epistemic Me project root(should be in a directory above the Server folder) with the following:

OPENAI_API_KEY=your_api_key_here

2. Run the server using the run.sh script:

./run.sh [flags]

The server will start on port 8080 by default.

The run.sh script is the main entry point for building, running, and testing the server. Before executing any command, it automatically runs a pre-build step using build.sh which:

• Generates protobuf files
• Fixes import paths
• Builds the Docker image

• No flags: Just builds and runs the server
• --daemon: Runs in daemon mode with live reload on code changes
• --test: Runs both integration and SDK tests
• --integration-test: Runs only integration tests
• --sdk-test: Runs only SDK tests

# Just run the server
./run.sh

# Run in daemon mode with live reload
./run.sh --daemon

# Run all tests (integration and SDK)
./run.sh --test

# Run only integration tests
./run.sh --integration-test

# Run only SDK tests
./run.sh --sdk-test

1. Run SDK tests:

docker build --target sdktest -t sdk-tests . && docker run --env-file <path_to_.env> sdk-tests

2. Run integration tests:

docker build --target inttest -t int-tests . && docker run --env-file <path_to_.env> int-tests

3. Run all tests:

# Build and run both test stages
docker build --target sdktest -t sdk-tests . && \
docker build --target inttest -t int-tests . && \
docker run --env-file <path_to_.env> sdk-tests && docker run --env-file <path_to_.env> int-tests

The run.sh script provides convenient test execution:

# Run all tests
./run.sh --test

# Run only integration tests
./run.sh --integration-test

# Run only SDK tests
./run.sh --sdk-test

When running tests:

1. The script first builds the project using build.sh
2. Starts the server in a Docker container
3. Waits for the server to be ready
4. Executes the specified test suite(s)
5. Reports test results
6. Exits with appropriate status code

1. Build the Docker image:

docker build --target dev -t epistemic-me-core .

2. Run the container:

docker run --env-file <path_to_.env> -p 8080:8080 epistemic-me-core

• proto/: Protocol Buffer definitions
• pb/: Generated Go code from Protocol Buffers
• svc/: Core service implementations
• server/: gRPC server implementation
• tests/: Integration and unit tests
  • integration/: Integration tests
  • sdk/: SDK tests
• ai/: AI helper implementations
• db/: Database and storage implementations

1. Make changes to the Protocol Buffer definitions in proto/
2. Run ./build.sh to regenerate the Go code
3. Implement your changes in the relevant service package
4. Add tests for your changes
5. Run tests to verify everything works
6. Submit your PR

The API is defined using Protocol Buffers. You can find the service definitions in the proto/ directory.

For detailed API documentation, please refer to the proto files:

• proto/models/*.proto: Data models
• proto/service.proto: Service definitions