Developer Getting Started¶

This guide is for contributors who want to clone Spector, run it locally, make a focused change, and verify it before opening a pull request. If you only want to try the product, start with the Quick Start or Installation guide instead.

Project-level contribution rules live in the README and CONTRIBUTING files. Read those before you push a branch; commits require a sign-off.

Prerequisites¶

Install these tools before cloning the repository:

Use a terminal that preserves normal shell quoting. On Windows PowerShell, prefer curl.exe in the examples below so PowerShell does not alias curl to Invoke-WebRequest.

Clone And Build¶

git clone https://github.com/spectrayan/spector.git
cd spector
mvn clean verify

A successful first build ends with BUILD SUCCESS. For a faster compile-only check while iterating:

mvn clean compile

To build all modules without running tests:

mvn clean package -DskipTests

Run The Local Node¶

The node module starts the embedded Armeria REST server on port 7070 by default:

mvn exec:java -pl spector-node -Dexec.mainClass="com.spectrayan.spector.node.SpectorNode"

In another terminal, verify the service:

curl http://localhost:7070/health
curl http://localhost:7070/api/v1/status

To use a different port, vector dimension, or API key, pass runtime arguments:

mvn exec:java -pl spector-node -Dexec.mainClass="com.spectrayan.spector.node.SpectorNode" -Dexec.args="7071 384 my-secret-key"

If you plan to test automatic embeddings or cognitive memory examples, start Ollama before the node:

ollama serve
ollama pull nomic-embed-text

Store A First Memory¶

With the node running, store a semantic memory:

curl -X POST http://localhost:7070/api/v1/memory/remember \
  -H "Content-Type: application/json" \
  -d '{
    "id": "dev-guide-1",
    "text": "Spector stores agent memories in semantic, episodic, working, and procedural tiers.",
    "tier": "SEMANTIC",
    "source": "USER_STATED",
    "tags": "developer-guide,memory"
  }'

The endpoint returns an accepted task response with the generated task id and memory id. See the REST API reference for the full request schema and related recall endpoints.

Architecture Map¶

Spector is a multi-module Maven project. Start with these areas when deciding where a change belongs:

For a deeper walkthrough, read the architecture overview, module guide, and module-specific README files.

Run Focused Tests¶

Run the full test suite before opening a pull request when practical:

mvn test

For focused work, test the touched module and any required upstream modules:

mvn test -pl spector-memory -am
mvn test -pl spector-node -am

To run a single test class:

mvn test -pl spector-core -Dtest=DotProductTest

Use mvn clean verify before submitting changes that touch public APIs, module boundaries, packaging, or documentation snippets that are checked during the site build.

IDE Setup¶

IntelliJ IDEA, Eclipse, and VS Code can import the root pom.xml as a Maven project. Set the project SDK to JDK 25 and let Maven manage compiler flags and module dependencies.

Useful defaults:

• Enable automatic Maven project import.
• Delegate build and test actions to Maven if IDE classpath resolution differs from the command line.
• Run the node from Maven with the spector-node command above, or create a run configuration for com.spectrayan.spector.node.SpectorNode.
• Keep generated build output under each module's target/ directory out of commits.

Contribution Checklist¶

Before opening a pull request:

• Confirm the issue is still open and no existing pull request solves it.
• Create a branch with a focused name, for example docs/getting-started-developer-guide.
• Keep the change small enough to review in one pass.
• Add or update tests/docs for behavior changes.
• Run the narrowest useful check, then the broader Maven check when the change warrants it.
• Commit with a conventional message and sign off: git commit -s -m "docs: add developer getting started guide".

Troubleshooting¶