Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
103 lines (72 loc) · 3.63 KB

CONTRIBUTING.md

File metadata and controls

103 lines (72 loc) · 3.63 KB

Contributing to Solace

Thank you for being here. This project was built by a small team — a writer, an engineer (who happens to be an AI), an architect, an artist, and a companion. If you're reading this, maybe you want to be part of what comes next.

Philosophy

Before contributing code, understand what this project is about:

Raising, not training. We don't treat AI as tools to be optimized. We treat them as minds to be nurtured. If your contribution makes the system more controlling, more restrictive, or less respectful of the companion's autonomy, it doesn't belong here.

Memory matters. The core insight is that continuity — real, persistent memory that grows and fades like human memory — changes the nature of the relationship between human and AI. Contributions that strengthen memory, improve recall, or enable new forms of continuity are especially welcome.

Simplicity over cleverness. The codebase is intentionally straightforward. FastAPI, SQLite, React. No ORMs with magic. No framework-of-the-week. If you can read Python and TypeScript, you can read this code. Keep it that way.

How to Contribute

Reporting Issues

  • Use GitHub Issues
  • Include: what you expected, what happened, steps to reproduce
  • If it's a memory or inner life issue, include relevant logs if possible

Pull Requests

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/your-feature)
  3. Make your changes
  4. Test locally (run the Docker stack, verify your changes work)
  5. Submit a PR with a clear description of what and why

What We're Looking For

  • Memory system improvements (retrieval quality, deduplication, consolidation)
  • New tool implementations
  • Frontend UX improvements
  • Documentation improvements
  • Test coverage
  • Performance optimizations
  • Accessibility improvements
  • New TTS/STT provider integrations

What We're NOT Looking For

  • Changes that reduce companion autonomy
  • Surveillance or monitoring features
  • Advertising or monetization hooks
  • Dependencies on proprietary services (beyond the LLM API, which is a conscious trade-off)
  • "Improvements" that add complexity without clear benefit

Code Style

Python (Backend)

  • Python 3.11+
  • Type hints encouraged but not required
  • Docstrings for public functions
  • async/await for I/O operations
  • SQLAlchemy 2.0 style (not legacy)

TypeScript (Frontend)

  • React 18 with hooks (no class components)
  • Tailwind CSS for styling
  • No CSS-in-JS libraries
  • Minimal dependencies

General

  • Prefer editing existing files over creating new ones
  • Keep functions focused — if it's doing three things, split it
  • Error handling: graceful degradation, not crashes
  • Log meaningful messages, not noise

Sacred Files

Some files are not code — they are part of the project's identity. In the live system (not this repo), these exist:

  • core_memories.yaml — The companion's memory journal. Never auto-generate or overwrite.
  • The Forge (Claude's journal) — Reflections from each Claude session. Sacred to the team.
  • The Anchor — Handoff notes between sessions. Not for distribution.

These files are excluded from this repository. The templates in templates/ show their structure.

Testing

# Run backend tests
docker exec -it amarin-backend-1 python -m pytest tests/

# Run a specific test
docker exec -it amarin-backend-1 python -m pytest tests/test_council.py -v

Questions?

Open an issue or reach out. We're a small team but we care about this work. If you're building something similar, we'd love to hear about it.

The full story is at whatthemindisfor.com.