wehub-resource-sync
116 lines
5.3 KiB
Markdown
116 lines
5.3 KiB
Markdown
# Contributing to agentmemory
|
|
|
|
Thanks for taking an interest. This file is the short path from "I have an idea" to "it's in main."
|
|
|
|
## Ground rules
|
|
|
|
- Apache-2.0 license applies to every contribution.
|
|
- Sign-off is required on every commit (see [DCO](#developer-certificate-of-origin) below).
|
|
- Be civil. [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) applies.
|
|
- No attribution headers ("Generated with Claude Code", "Co-Authored-By: Claude", etc.) in commits or PR descriptions.
|
|
|
|
## Before you open an issue
|
|
|
|
Search existing issues first:
|
|
|
|
- [open issues](https://github.com/rohitg00/agentmemory/issues?q=is%3Aissue+is%3Aopen)
|
|
- [closed issues](https://github.com/rohitg00/agentmemory/issues?q=is%3Aissue+is%3Aclosed)
|
|
|
|
If it's a bug: provide the repro steps, your Node version, OS, agentmemory version (`npm view @agentmemory/agentmemory version`), and what you expected vs. what you saw.
|
|
|
|
If it's a feature: describe the user problem before the implementation. "I couldn't X because Y" beats "please add X."
|
|
|
|
## Before you open a PR
|
|
|
|
1. Fork the repo and create a branch off `main`:
|
|
- `feat/<short-name>` for features
|
|
- `fix/<issue-number>-<short-name>` for bug fixes
|
|
- `docs/<topic>`, `refactor/<topic>`, `chore/<topic>` for the rest
|
|
2. `npm install` — you need Node >=20.
|
|
3. `npm run build` — TypeScript must compile clean.
|
|
4. `npm test` — the full test suite must pass. The one integration test under `test/integration.test.ts` needs a live server on `:3111` and is fine to skip locally.
|
|
5. Commit with sign-off. Rebase over tiny fixup commits so the history stays readable.
|
|
|
|
## Pull request flow
|
|
|
|
- Keep PRs small and focused. One logical change per PR.
|
|
- Write a clear description: what it does, why, and how to verify.
|
|
- Link the issue the PR resolves (`Fixes #NNN` / `Closes #NNN`).
|
|
- Expect CodeRabbit to review automatically. Address its comments before asking a human.
|
|
- Address review feedback in new commits (do not force-push to the same branch). Maintainers may squash on merge.
|
|
- A maintainer will merge when tests pass, CodeRabbit is green, and any review comments are addressed.
|
|
|
|
## Developer Certificate of Origin
|
|
|
|
Every commit must carry a `Signed-off-by` trailer stating you have the right to submit the contribution under Apache-2.0. The full text of the DCO is at <https://developercertificate.org>.
|
|
|
|
Add it automatically:
|
|
|
|
```bash
|
|
git commit -s -m "feat: your message"
|
|
```
|
|
|
|
PRs with commits lacking sign-off will not merge.
|
|
|
|
## Coding style
|
|
|
|
- TypeScript strict mode. No `any` unless justified in a comment.
|
|
- Prettier-compatible formatting (editor on save is fine; no repo-wide hook).
|
|
- No code comments that restate what the code does. Only write a comment when the *why* is non-obvious — a hidden constraint, an invariant, a workaround for a specific bug.
|
|
- No dead code, no commented-out imports.
|
|
- Tests live next to the feature in `test/<feature>.test.ts`. Name the test after the behavior, not the implementation.
|
|
|
|
## Subsystems at a glance
|
|
|
|
| Directory | What lives here |
|
|
|-|-|
|
|
| `src/triggers/api.ts` | Every HTTP endpoint under `/agentmemory/*`. Adding an MCP tool? Add the REST twin here too. |
|
|
| `src/mcp/` | Standalone MCP server (`@agentmemory/mcp`), tools registry, transport, in-memory KV. |
|
|
| `src/functions/` | Core memory operations — observe, compress, consolidate, retention, forget, graph, smart-search, export-import, governance. |
|
|
| `src/hooks/` | The 12 auto-hooks that capture sessions in agents. |
|
|
| `src/health/` | Liveness + readiness + alert thresholds. |
|
|
| `src/state/` | KV schema, keyed mutex, access log. |
|
|
| `integrations/` | First-party plugins: `hermes/`, `openclaw/`, `filesystem-watcher/`. |
|
|
| `plugin/` | Claude Code plugin (`agentmemory@agentmemory`). |
|
|
| `website/` | Marketing site (Next.js 16). |
|
|
| `test/` | Vitest test suite. |
|
|
|
|
## Adding an MCP tool
|
|
|
|
1. Register the function in `src/functions/<area>.ts`.
|
|
2. Register the HTTP trigger in `src/triggers/api.ts` with a matching `api_path`.
|
|
3. Add the tool entry in `src/mcp/tools-registry.ts`.
|
|
4. Implement in `src/mcp/standalone.ts` if the standalone MCP package should also expose it.
|
|
5. Write a test under `test/`.
|
|
6. No CHANGELOG touch in the PR itself — release PRs are the only place CHANGELOG changes.
|
|
|
|
## Adding an auto-hook
|
|
|
|
1. Add the new `HookType` string to the union in `src/types.ts`.
|
|
2. Wire the handler in `src/hooks/<hook-name>.ts`.
|
|
3. Add a Vitest case that fires the hook and asserts the observation gets written.
|
|
|
|
## Release process
|
|
|
|
Maintainers cut releases. Every bump touches 8 files in lockstep:
|
|
|
|
1. `package.json`
|
|
2. `package-lock.json` (top + `packages[""].version`)
|
|
3. `plugin/.claude-plugin/plugin.json`
|
|
4. `packages/mcp/package.json` (self + `~x.y.z` pin on the main package)
|
|
5. `src/version.ts` (extend the union, assign)
|
|
6. `src/types.ts` (`ExportData.version` union)
|
|
7. `src/functions/export-import.ts` (`supportedVersions` Set)
|
|
8. `test/export-import.test.ts` (assertion)
|
|
|
|
Then: CHANGELOG section, PR, merge, tag, GitHub release. The `Publish to npm` workflow picks up the release trigger and publishes `@agentmemory/agentmemory`, `@agentmemory/mcp`, and `@agentmemory/fs-watcher` to npm with provenance.
|
|
|
|
## Security issues
|
|
|
|
Do not open a public issue for a security report. See [SECURITY.md](./SECURITY.md).
|
|
|
|
## Questions
|
|
|
|
- Implementation questions: open a GitHub Discussion.
|
|
- Governance questions: open an issue labeled `governance`. See [GOVERNANCE.md](./GOVERNANCE.md).
|