I want to contribute code
Read this when you want to send Mirrai a fix or a feature and are getting ready to open a PR. If you only want to report a bug, skip to “How to report problems”.
The flow
- Fork the repository to your own account.
- Create a branch with a name that says what it does:
git checkout -b fix/memory-recall-scoring
- Make the change — keep it small and complete; one PR does one thing.
- Run the checks (next section) and get them green before pushing.
- Open a PR describing what changed, why, and how you verified it. Reference the related issue number if there is one.
What you should see: CI checks pass on the PR page; review comments arrive in the PR thread.
Before you open a PR
Run all three; all three must exit with code 0:
pnpm check
pnpm test
pnpm fidelity:gate
pnpm check— TypeScript type checking.pnpm test— the repo’s vitest suite.pnpm fidelity:gate— a deterministic regression gate: a few seconds, no cost, the same answer every run. It guards bottom lines that shouldn’t change silently and stops you with a non-zero exit code if they regress.
Especially don’t skip these if you touched interfaces, schema, or prompt-related code.
Two common extension points
Adding a new LLM provider (OpenAI-compatible services can reuse the existing implementation):
- Implement the
LLMProviderinterface underserver/llm/providers/. - Register it in
server/llm/index.ts.
Adding a new emotional state:
drizzle/schema.ts— add the state to the enum.server/_core/persona-utils.ts— add its trigger words and description.client/src/pages/Chat.tsx/HomePage.tsx— update the state display in the UI.
What to put in a PR description
Three parts are enough: what changed, why, and how you verified it (which commands you ran, which paths you clicked through). PRs with screenshots or logs get reviewed faster — redact them first.
Code style
- Strict TypeScript — no bypassing the type checker.
- Follow existing patterns: new tables go
drizzle/schema.ts→server/db.ts→server/routers.ts→ client hooks; a new LLM provider implements the interface underserver/llm/providers/and is registered inserver/llm/index.ts. - No unnecessary abstractions. Three repeated lines beat a one-use wrapper.
- Commit messages say why, not just what.
The repo has finer detail in CONTRIBUTING.md (issue and PR templates live under .github/).
How to report problems
| Situation | Where |
|---|---|
| Bugs and feature requests | GitHub Issues |
| Usage questions and ideas | GitHub Discussions |
| Security vulnerabilities | Report privately via SECURITY.md in the repo — do not open a public issue |
A good bug report includes four things: version number, install method (Docker / source / installer), reproduction steps, and observed vs. expected behavior. Attach logs where you can (redact them — never paste API keys or chat content).
License
Mirrai is released under the MIT License. By sending a PR you contribute under the same MIT terms; any contributor-agreement specifics are governed by CONTRIBUTING.md.
One last note: this project deals with real people and real feelings. For changes touching personas, memory, or the graduation mechanism, think about how they land on the person using it.