Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
116 lines (76 loc) · 7.82 KB

CONTRIBUTING.md

File metadata and controls

116 lines (76 loc) · 7.82 KB
Raw

Contributing to Graphnosis

Thanks for considering a contribution. Before opening a PR, please read this guide so the work fits the project's direction and your time is well spent.

Internal release sequencing and cross-repo work queues are not tracked in this repository — they live in the owner's private backlog. What follows is the public gate: what belongs in the SDK, what doesn't, and how to propose something that might.

Project shape

Graphnosis is intentionally a small, focused, in-process SDK for AI-native dual-graph knowledge representation. It does one thing: build, query, and persist typed knowledge graphs with deterministic semantics and offline-first defaults.

Anything beyond those primitives lives in separate packages or separate repositories. This separation keeps the SDK easy to embed, easy to audit, and easy to evolve.

In scope — core SDK

These belong in @nehloo/graphnosis:

  • Graph engine. Dual-graph (directed + undirected edges) data model, node/edge types, confidence + temporal fields.
  • Ingestion parsers. Markdown, HTML, JSON, CSV, PDF, plain text. New parsers for common document formats are welcome via issue discussion.
  • Indexing. TF-IDF index with pluggable analyzers, in-memory embedding index with pluggable adapters.
  • Querying. query() (TF-IDF), queryHybrid() (TF-IDF + embeddings), prompt() builders, subgraph context serialization.
  • Corrections. edit, deleteNode, supersede, correct, importMarkdown, forgetByTopic, forgetByTimeWindow, previewForgetTopic, retired. Soft-delete semantics. edit supersedes rather than overwriting — the prior version stays readable.
  • Confidence. setConfidence / setConfidences — change how much a memory counts without minting or retiring anything.
  • Persistence. The .gai binary format (MessagePack body, big-endian header, checksum, optional HMAC signing) as specified in SPEC.md, SQLite store, buffer-based I/O for serverless.
  • Determinism. asOf — one caller-supplied instant for a whole query, so the same question against an unchanged graph returns the same answer indefinitely.
  • Failure classification. Stable error codes and classes (GraphnosisError, isCorruption, isVersionSkew, isCallerError) so a consumer can branch on the class instead of matching message text.
  • Analyzer migration. migrateAnalyzer — move an existing index to a different analyzer deliberately, with a count of the terms recovered.
  • Reflection. reflect() — contradictions, decayed nodes, surprising connections.
  • Adapter interfaces. EmbeddingAdapter, TextAnalyzer. New built-in adapters for major providers (OpenAI, Voyage, Cohere) live in @nehloo/graphnosis/adapters/*.
  • Federation primitive. queryGraphs([...]) for in-process cross-graph queries.
  • MCP server. Single-graph stdio MCP server for use with Claude Desktop and similar clients.
  • Documentation and examples for all of the above.

Improvements to performance, correctness, ergonomics, and test coverage of anything in this list are always welcome.

The format, and where it is going

The .gai format is specified in SPEC.md, separately from this SDK, because a format with one implementation and no written specification is a file layout rather than something anyone else can adopt.

v1 is what ships today and is described by SPEC.md §1–§7. Files written by 0.7 and later still load.

v2 is proposed in SPEC.md §8 and nothing in it is implemented. It is intended to be the only breaking version the format ever has, which means everything in it lands together or not at all: (id, rev) node identity so two revisions of one memory can coexist and a merge has somewhere to put a conflict; an authority ceiling carried in the file so a skill keeps its constraints when it moves between applications; byte-level reproducibility; the skill subgraph convention stated normatively; and conformance levels.

Conformance is declared per layer — L1 container, L2 model, L3 retrieval and authority. Most implementations need only L1 or L2, and declaring L2 is a complete claim rather than a partial one: it means every memory in the file round-trips faithfully, without promising to rank them the same way.

Proposals that would change the format are welcome as issues, but the bar is deliberately high and the window is v2. After that, extension happens through the must-understand feature list in the header rather than a version bump.

Out of scope

Anything outside the core graph-engine primitives listed above. If you're unsure whether your idea fits, open an issue with the proposal label and we'll discuss before you invest implementation time. The default for borderline cases is "build it as a separate package that depends on Graphnosis" (we'll happily link to community packages from the README).

Process for "I think this might be in scope but I'm not sure"

Open an issue with the proposal label. Describe:

  1. What you want to build
  2. What problem it solves
  3. Why you think it belongs in the SDK rather than an adjacent package

We'll discuss before you invest implementation time. The default answer for borderline cases is "build it as a separate package" — but there are exceptions, and a short conversation is the cheapest way to get to the right answer.

Before you open a PR

  1. Open an issue first for anything larger than a typo, doc fix, or one-file bug fix. This avoids wasted work if the change conflicts with project direction.
  2. One change per PR. Small, focused PRs review faster and merge sooner.
  3. Match the existing style. TypeScript strict mode, no any without explicit justification, prefer named exports, prefer pure functions where reasonable.
  4. Add or update tests when fixing bugs or adding features. The benchmark suite (tests/longmemeval) should not regress.
  5. Update the docs if your change affects public API surface.

CLA — Contributor License Agreement

Before your first PR can be merged, you'll be asked to sign the project's Contributor License Agreement. This happens automatically — a bot will comment on your PR with a one-click sign link.

Why a CLA? Graphnosis is licensed Apache-2.0 and will remain so. The CLA preserves the project's flexibility to evolve while ensuring all contributions can be redistributed under the project's license. It's standard practice for actively maintained open-source projects.

It takes about 30 seconds.

Workflow

# 1. Fork and clone
git clone https://github.com/<your-username>/Graphnosis.git
cd Graphnosis

# 2. Install dependencies
npm install

# 3. Run tests and the build
npm run lint:lib
npm run build:lib

# 4. Make your changes on a branch
git checkout -b fix/your-thing

# 5. Commit with a clear message — conventional commit style is appreciated
#    feat: ..., fix: ..., docs: ..., refactor: ..., test: ..., chore: ...

# 6. Push and open a PR against `main`

Communication

  • Bug reports → GitHub Issues with reproducer
  • Feature proposals → GitHub Issues, label proposal, referencing the relevant in-scope / format section above
  • Security issues → please do not open a public issue; email security@graphnosis.com

What we will NOT accept

  • Breaking changes to the .gai binary format without prior issue discussion and a clear migration story
  • Changes that require network egress from the core SDK (the SDK is offline-first; network-using features belong in adapter packages)
  • Vendored binaries or large model files in this repository
  • PRs that introduce a new runtime dependency without justification in the issue

Recognition

Substantial contributions are credited in release notes. We're happy to add contributors to a CONTRIBUTORS.md file (and to the npm package metadata for sustained contributors).

Thanks for helping make Graphnosis better.