Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
42 lines (27 loc) · 1.95 KB

CONTRIBUTING.md

File metadata and controls

42 lines (27 loc) · 1.95 KB
Raw

Contributing to engram

engram is deliberately small: one module per concern (store, search, init, mcp, cli) and a handful of focused tests. The best contributions respect that.

Before you write code

  • Bugs and new-agent support: open an issue first (use the templates in .github/ISSUE_TEMPLATE/). A 5-line discussion saves a 50-line PR.
  • Features on the roadmap (semantic search, persistent index, sync, web UI): comment on the relevant issue before starting, so work isn't duplicated.

The bar for a new dependency is high

The current deps are minisearch (BM25), @modelcontextprotocol/sdk (MCP), yaml (frontmatter), and commander (CLI). That's it. Before adding anything:

  1. Can the Node stdlib do it? Use the stdlib.
  2. Can ~20 lines do it? Write the lines.
  3. Only then propose the dep in the issue/PR and say why the above two failed.

No ORM, no SQLite, no vector DB, no embeddings, no cloud SDK, no telemetry — these are explicit v1 constraints, not oversights.

Local dev

git clone https://github.com/Victorchatter/engramkit
cd engramkit
npm install
npm test            # vitest — must stay green and deterministic
npx tsc --noEmit    # must pass clean

Before opening a PR:

  • npm test and npx tsc --noEmit both pass.
  • If you touched storage, run the suite a few times — engram had a fun YAML-type-coercion flake that only showed on certain ids; determinism matters.
  • Don't add a config knob for a constant. Don't add an abstraction with one implementation. Match the existing style (lazy-senior: shortest working diff, fewest files).

Committing

Run engram init in this repo if you want the memory layer active while you work — but don't commit the generated .engram/, .claude/, .mcp.json, etc. from your dev experiments unless they're genuine project improvements. (The .gitignore keeps them out.)

License

By contributing you agree your changes are MIT-licensed, same as the rest of engram.