Skip to content

Commit 73b91d4

Browse files
MichaelAdamGrobermanMichaelAdamGroberman
committed
docs: governance files + README badges + pyproject metadata
Mirrors the gr0m_mem main-branch governance set onto semantic: CONTRIBUTING.md, CODE_OF_CONDUCT.md, issue and PR templates, README badges, and full pyproject.toml [project.urls] + classifiers. semantic branch now correctly identifies itself as the full build (ChromaDB + SQLite-vector + Ollama) with links to the main branch as the zero-install alternative.
1 parent fb2e95b commit 73b91d4

8 files changed

Lines changed: 388 additions & 11 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
name: Bug report
2+
description: Something isn't working as documented
3+
title: "bug: "
4+
labels: ["bug", "triage"]
5+
assignees:
6+
- MichaelAdamGroberman
7+
body:
8+
- type: markdown
9+
attributes:
10+
value: |
11+
Thanks for taking the time to file a bug report. Please fill
12+
out the sections below so the maintainer can reproduce the
13+
issue without a back-and-forth.
14+
15+
**Security issues:** please do NOT use this form. Use the
16+
Security tab's "Report a vulnerability" button instead.
17+
- type: input
18+
id: version
19+
attributes:
20+
label: Gr0m_Mem version
21+
description: Output of `gr0m_mem --version` (or `pip show gr0m-mem | grep Version`)
22+
placeholder: "0.1.0"
23+
validations:
24+
required: true
25+
- type: input
26+
id: python
27+
attributes:
28+
label: Python version
29+
description: Output of `python --version`
30+
placeholder: "3.12.1"
31+
validations:
32+
required: true
33+
- type: input
34+
id: os
35+
attributes:
36+
label: OS and architecture
37+
description: macOS / Linux / Windows + arm64 / x86_64
38+
placeholder: "macOS 14.4, arm64"
39+
validations:
40+
required: true
41+
- type: dropdown
42+
id: backend
43+
attributes:
44+
label: Active backend
45+
description: Output of `gr0m_mem doctor` includes a "backend:" line
46+
options:
47+
- sqlite_fts (zero-install default)
48+
- sqlite_vec (Ollama-backed)
49+
- chromadb (full extra)
50+
- I don't know
51+
validations:
52+
required: true
53+
- type: textarea
54+
id: reproduce
55+
attributes:
56+
label: Minimal reproduction
57+
description: The smallest sequence of commands or code that reproduces the bug
58+
render: shell
59+
placeholder: |
60+
gr0m_mem remember --kind identity --text "Michael"
61+
gr0m_mem wakeup --tokens 200
62+
validations:
63+
required: true
64+
- type: textarea
65+
id: expected
66+
attributes:
67+
label: Expected behavior
68+
validations:
69+
required: true
70+
- type: textarea
71+
id: actual
72+
attributes:
73+
label: Actual behavior
74+
description: Include any stack traces, error messages, or unexpected output
75+
render: shell
76+
validations:
77+
required: true
78+
- type: textarea
79+
id: logs
80+
attributes:
81+
label: Relevant logs
82+
description: Output of `gr0m_mem doctor` and any relevant server/CLI logs
83+
render: shell
84+
- type: checkboxes
85+
id: terms
86+
attributes:
87+
label: Code of Conduct
88+
options:
89+
- label: I agree to follow this project's Code of Conduct
90+
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Security vulnerability report
4+
url: https://github.com/MichaelAdamGroberman/gr0m_mem/security/advisories/new
5+
about: Report a security issue privately. Please do NOT open a public issue for security problems.
6+
- name: Questions and discussions
7+
url: https://github.com/MichaelAdamGroberman/gr0m_mem/discussions
8+
about: Ask a question or start a discussion (enable Discussions on the repo first if the link 404s).

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Feature request
2+
description: Suggest an improvement or new capability
3+
title: "feat: "
4+
labels: ["enhancement", "triage"]
5+
assignees:
6+
- MichaelAdamGroberman
7+
body:
8+
- type: markdown
9+
attributes:
10+
value: |
11+
Thanks for suggesting a feature. The most useful feature
12+
requests start with the **problem** you are trying to solve,
13+
not the solution you have in mind — it lets the maintainer
14+
suggest alternatives you may not have considered.
15+
- type: textarea
16+
id: problem
17+
attributes:
18+
label: What problem are you trying to solve?
19+
description: Describe the pain point in concrete terms. Who experiences it, how often, what is the current workaround?
20+
validations:
21+
required: true
22+
- type: textarea
23+
id: proposed
24+
attributes:
25+
label: Proposed solution
26+
description: What you would like Gr0m_Mem to do. Include the shape of the API, CLI command, or tool signature if you have one in mind.
27+
validations:
28+
required: true
29+
- type: textarea
30+
id: alternatives
31+
attributes:
32+
label: Alternatives you considered
33+
description: Other designs you weighed and why they did not fit
34+
- type: textarea
35+
id: context
36+
attributes:
37+
label: Additional context
38+
description: Links, screenshots, related issues, prior art in other projects
39+
- type: checkboxes
40+
id: terms
41+
attributes:
42+
label: Code of Conduct
43+
options:
44+
- label: I agree to follow this project's Code of Conduct
45+
required: true

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
<!--
2+
Thanks for the pull request! Before you submit, please check off
3+
every item in the "Required checks" list. If anything is unchecked,
4+
the maintainer will ask for it — saving a round trip just means
5+
filling the list out now.
6+
-->
7+
8+
## What does this change?
9+
10+
<!-- 1-3 sentences describing the user-visible effect. -->
11+
12+
## Why?
13+
14+
<!-- Link the issue this fixes, or describe the problem if there is no issue. -->
15+
16+
Closes #
17+
18+
## How did you test it?
19+
20+
<!-- Commands you ran, tests you added, before/after output. -->
21+
22+
```console
23+
$ .venv/bin/python -m pytest -q tests/unit/test_<your_area>.py
24+
25+
```
26+
27+
## Required checks
28+
29+
- [ ] The three CI commands pass locally:
30+
- [ ] `ruff check gr0m_mem tests benchmarks`
31+
- [ ] `mypy gr0m_mem benchmarks`
32+
- [ ] `pytest -q`
33+
- [ ] If this touches the KG, loop-prevention, or retrieval surfaces, the loop-prevention benchmark still passes in strict mode:
34+
- [ ] `python -m benchmarks.loop_prevention.run --strict`
35+
- [ ] New public API is covered by a test in `tests/unit/`, `tests/temporal/`, or `tests/integration/`
36+
- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, etc.)
37+
- [ ] If this changes behavior users will notice, `CHANGELOG.md` has an entry under `## [Unreleased]`
38+
- [ ] I have read the [Code of Conduct](CODE_OF_CONDUCT.md) and I am willing to follow it
39+
40+
## Optional
41+
42+
- [ ] This is a breaking change
43+
- [ ] This adds a new dependency (justify in the description)
44+
- [ ] This changes the on-disk database schema (describe the migration)

‎CODE_OF_CONDUCT.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Code of Conduct
2+
3+
This project follows the [Contributor Covenant][covenant], version 2.1.
4+
The full text (including the enforcement ladder and the definitions of
5+
unacceptable behavior) is hosted at the canonical URL below — we do not
6+
duplicate it here, so any upstream clarification applies automatically:
7+
8+
> **<https://www.contributor-covenant.org/version/2/1/code_of_conduct/>**
9+
10+
## Scope
11+
12+
The Covenant applies to every project space (this repository, its
13+
issue tracker, pull request threads, and any discussion channel the
14+
project maintains) and to every individual representing the project in
15+
public.
16+
17+
## Reporting
18+
19+
If you experience or witness behavior that violates the Covenant:
20+
21+
1. Open a **private vulnerability report** via the GitHub Security tab
22+
(same channel as security disclosures — see [SECURITY.md](SECURITY.md)).
23+
This is the preferred path because it is encrypted end-to-end and
24+
only the maintainer sees the report.
25+
2. Or contact the maintainer directly through the LinkedIn profile
26+
linked in [README.md](README.md#contact).
27+
28+
Reports are handled by the project maintainer. All reports are treated
29+
confidentially; the reporter's identity is never shared without their
30+
explicit consent.
31+
32+
## Attribution
33+
34+
This Code of Conduct is adapted from the [Contributor Covenant][covenant],
35+
version 2.1, available at
36+
<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
37+
38+
Community Impact Guidelines were inspired by Mozilla's code of conduct
39+
enforcement ladder.
40+
41+
For answers to common questions about this code of conduct, see the FAQ
42+
at <https://www.contributor-covenant.org/faq>. Translations are
43+
available at <https://www.contributor-covenant.org/translations>.
44+
45+
[covenant]: https://www.contributor-covenant.org

‎CONTRIBUTING.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Contributing to Gr0m_Mem
2+
3+
Thanks for your interest! This file is the practical "how do I help"
4+
guide. The governance contract is in
5+
[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) and the disclosure policy
6+
is in [`SECURITY.md`](SECURITY.md).
7+
8+
## Before you open an issue or PR
9+
10+
- **Security issues** — please do NOT open a public issue. Use the
11+
GitHub private vulnerability reporting button on the Security tab,
12+
or email the maintainer. See [`SECURITY.md`](SECURITY.md) for the
13+
full disclosure policy.
14+
- **Bug reports** — use the **Bug report** issue template
15+
(`.github/ISSUE_TEMPLATE/bug_report.yml`). Include:
16+
- Gr0m_Mem version (`gr0m_mem --version`)
17+
- Python version (`python --version`)
18+
- OS and arch (`uname -a` on Unix)
19+
- Backend selected (`gr0m_mem doctor`)
20+
- A minimal reproducer
21+
- The actual error or unexpected behavior
22+
- **Feature requests** — use the **Feature request** template. Tell us
23+
the problem you're trying to solve before the solution you have in
24+
mind. We're more likely to merge a small change that addresses a
25+
real pain point than a big change that adds options.
26+
- **Questions** — open a GitHub Discussion instead of an issue.
27+
28+
## Local development setup
29+
30+
```bash
31+
# Clone your fork
32+
git clone https://github.com/<you>/gr0m_mem.git
33+
cd gr0m_mem
34+
35+
# Use uv (fast) — recommended
36+
uv venv --python 3.12
37+
uv pip install -e ".[dev]"
38+
39+
# Or use plain pip + venv
40+
python3.12 -m venv .venv
41+
source .venv/bin/activate
42+
pip install -e ".[dev]"
43+
```
44+
45+
## Running the checks locally
46+
47+
The CI runs the exact same three commands, so if these pass locally
48+
the PR will pass CI:
49+
50+
```bash
51+
.venv/bin/python -m ruff check gr0m_mem tests benchmarks
52+
.venv/bin/python -m mypy gr0m_mem benchmarks
53+
.venv/bin/python -m pytest -q
54+
```
55+
56+
For the loop-prevention benchmark (required to stay at 100%):
57+
58+
```bash
59+
.venv/bin/python -m benchmarks.loop_prevention.run --strict
60+
```
61+
62+
## Coding conventions
63+
64+
- **Python 3.10+**, `from __future__ import annotations` at the top of
65+
every file
66+
- **Ruff** with the lint rules in `pyproject.toml` (E, F, I, B, UP, SIM).
67+
No ignores without a comment explaining why
68+
- **Mypy `--strict`** — every function signature gets type hints, no
69+
`Any` leakage across module boundaries
70+
- **Conventional Commits** for commit messages (`feat:`, `fix:`,
71+
`docs:`, `test:`, `ci:`, `refactor:`, `perf:`, `chore:`, `sec:`,
72+
optionally scoped like `feat(store):`)
73+
- **Tests first** for any non-trivial change. Public API changes need
74+
tests in `tests/unit/` (or `tests/temporal/` for KG changes, or
75+
`tests/integration/` for CLI/hook round trips)
76+
- **No LLM calls from inside the library** — Gr0m_Mem produces context
77+
blocks, it does not reason about them. See the rationale in
78+
[`README.md`](README.md)
79+
80+
## Pull request flow
81+
82+
1. Open an issue first if the change is non-trivial — "non-trivial" =
83+
anything that adds or removes a public symbol, changes the on-disk
84+
format, or touches the MCP tool surface
85+
2. Fork, branch (`feat/short-topic` or `fix/short-topic`), make the
86+
change, make sure the three local checks pass
87+
3. Open the PR using the template (`.github/PULL_REQUEST_TEMPLATE.md`)
88+
4. CI runs across macOS + Ubuntu on Python 3.10, 3.11, 3.12. All three
89+
matrix cells plus the loop-prevention benchmark must be green
90+
5. The maintainer is `@MichaelAdamGroberman` and is auto-requested as
91+
a reviewer via `CODEOWNERS`
92+
93+
## License
94+
95+
By contributing you agree that your contribution will be licensed
96+
under the [MIT License](LICENSE) that covers this project.

‎README.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,19 @@
1-
# Gr0m_Mem
1+
# Gr0m_Mem — semantic branch
22

3-
Zero-install persistent memory brain for **any** LLM runtime (Claude Code, Claude Desktop, Cursor, Gemini CLI, Continue, Cline, Zed, OpenAI Codex CLI, Aider, raw OpenAI / Anthropic / Gemini APIs, or a local Llama) that **stops the model from re-asking and re-deriving** across sessions.
3+
[![CI](https://github.com/MichaelAdamGroberman/gr0m_mem/actions/workflows/ci.yml/badge.svg?branch=semantic)](https://github.com/MichaelAdamGroberman/gr0m_mem/actions/workflows/ci.yml)
4+
[![PyPI](https://img.shields.io/pypi/v/gr0m-mem.svg?logo=pypi&logoColor=white&label=PyPI)](https://pypi.org/project/gr0m-mem/)
5+
[![Python](https://img.shields.io/pypi/pyversions/gr0m-mem.svg?logo=python&logoColor=white)](https://pypi.org/project/gr0m-mem/)
6+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
7+
[![Downloads](https://static.pepy.tech/badge/gr0m-mem)](https://pepy.tech/project/gr0m-mem)
8+
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
9+
[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
410

5-
> **This is the `main` branch — the zero-install core.**
6-
> No ChromaDB, no Ollama, no 1 GB embedding model. Pure CPython stdlib + a couple of pure-Python wheels. `pip install gr0m-mem` and it just works.
11+
Persistent memory brain for **any** LLM runtime (Claude Code, Claude Desktop, Cursor, Gemini CLI, Continue, Cline, Zed, OpenAI Codex CLI, Aider, raw OpenAI / Anthropic / Gemini APIs, or a local Llama) that **stops the model from re-asking and re-deriving** across sessions.
12+
13+
> **This is the `semantic` branch — the full build with ChromaDB + SQLite-vector + Ollama.**
14+
> Adds HNSW cosine retrieval and Ollama-backed embeddings on top of the zero-install core. Install with `pip install "gr0m-mem[chromadb]"` or pull Ollama and set `GR0M_MEM_BACKEND=sqlite_vec`.
715
>
8-
> For semantic retrieval (ChromaDB HNSW + Ollama embeddings) switch to the [`semantic`](https://github.com/MichaelAdamGroberman/gr0m_mem/tree/semantic) branch.
16+
> For the minimal zero-install build (pure SQLite FTS5, no extras, no embedding model) switch to the [`main`](https://github.com/MichaelAdamGroberman/gr0m_mem/tree/main) branch.
917
1018
## Works with any LLM
1119

0 commit comments

Comments
 (0)