chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
+115
@@ -0,0 +1,115 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user