diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 2fefb35..b927eef 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "session-memory", "description": "Builds persistent intelligence — both project state and knowledge — across your working world. Nine commands for committing sessions, recalling context, searching knowledge, capturing lessons and gotchas, taking quick notes, running weekly reviews, viewing timelines, archiving projects, and maintaining memory health. Works for any kind of work: client engagements, business development, strategy, operations, hiring, research, learning, and technical projects.", - "version": "3.0.0", + "version": "3.0.1", "author": { "name": "BrightWay AI", "url": "https://brightwayai.com" diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..e99625d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,32 @@ +--- +name: Bug report +about: Something isn't working as expected +title: "[Bug] " +labels: bug +assignees: '' +--- + +**Platform** +- [ ] Cowork (Claude Desktop) +- [ ] Claude Code +- [ ] Other (describe below) + +**Command / skill affected** + + +**What happened** + + +**What you expected** + + +**Steps to reproduce** +1. +2. +3. + +**Memory file contents (if relevant)** + + +**Additional context** + diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..d998550 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,25 @@ +--- +name: Feature request +about: Suggest a new capability or improvement +title: "[Feature] " +labels: enhancement +assignees: '' +--- + +**Use case** + + +**Command or area affected** + + +**Proposed behavior** + + +**Example** + + +**Alternatives considered** + + +**Additional context** + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..f7deb16 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,21 @@ +## Summary + + + +## Changes + +- + +## Checklist + +- [ ] Command files updated (if behavior changed) +- [ ] Matching skill files updated (command ↔ skill parity) +- [ ] `plugin.json` version bumped (if user-visible change) +- [ ] README updated (command table, setup, or description) +- [ ] `CHANGELOG.md` entry added under `[Unreleased]` +- [ ] Frontmatter (`description`) is accurate on new/changed files +- [ ] Cowork `commands/` and Claude Code `.claude/commands/` stay consistent (if both exist) + +## Test plan + + diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml new file mode 100644 index 0000000..027e40d --- /dev/null +++ b/.github/workflows/validate.yml @@ -0,0 +1,19 @@ +name: Validate + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Validate plugin.json + run: python3 -c "import json; json.load(open('.claude-plugin/plugin.json'))" + + - name: Check commands, skills, optional .claude/commands + run: python3 scripts/check_repo.py diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c1a98a3 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,67 @@ +# Changelog + +All notable changes to the Session Memory Plugin are documented here. + +Format follows [Keep a Changelog](https://keepachangelog.com/). Versions match `plugin.json`. + +## [Unreleased] + +_Nothing yet._ + +## [3.0.1] + +### Added +- MIT `LICENSE` file (matches `plugin.json` license field). +- `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`. +- `CHANGELOG.md` as the canonical version history (README changelog remains a summary). +- GitHub issue templates (bug report, feature request) and pull request template. +- `docs/ARCHITECTURE.md` describing command/skill flow and memory layout. +- CI workflow **Validate** — JSON checks for `plugin.json`, frontmatter checks for command/skill markdown (and `.claude/commands` when present). +- `scripts/check_repo.py` used by CI. + +## [3.0.0] + +### Added +- **File-based storage** — memory now persists to `~/Documents/Claude/memory/` as markdown files. +- Two-tier structure: `DASHBOARD.md` for fast orientation + individual node files for detail. +- Node-to-file mapping: `client:acme-corp` → `memory/client/acme-corp.md`. +- Directories created dynamically from node prefixes — any prefix is valid. +- Every write operation updates both the node file and the dashboard. +- Archive support: `/forget --archive` moves files to `memory/archive/`. +- `/cleanup` now audits actual files on disk, detects orphaned entries and missing files. +- All 9 commands updated with explicit storage instructions. + +## [2.2.0] + +### Changed +- **Business-operator friendly** — all examples, taxonomy, and language updated for general business use (not just technical projects). +- Node conventions now lead with client work, bizdev, strategy, and ops. +- Added strategy/planning node type (`strategy:q2-growth`, `strategy:pricing`). +- All knowledge examples rewritten for business contexts (proposals, procurement, pricing, onboarding, retention). + +## [2.1.0] + +### Added +- **Knowledge-first redesign** — memory now captures insights, lessons, mental models, gotchas, recipes, and corrected beliefs as first-class entry types. +- `/learn` — quick knowledge capture without full session extraction. +- `/note` — one-liner capture for quick facts. +- `/review` — synthesized weekly digest with "Learned" as a prominent section. + +### Changed +- `/recall` now surfaces knowledge entries prominently (not buried under project state). +- `/recall [topic]` — topic-based knowledge recall across all projects. +- `/search` redesigned to prioritize knowledge entries for "how/what/why" queries. +- `/remember` extraction expanded to cover both project state and knowledge categories. +- Knowledge entries preserved longer than logs during memory consolidation. + +## [2.0.0] + +### Added +- `/search`, `/forget`, `/timeline`, `/cleanup` commands. +- Priority system, staleness tracking, blocker tracking, people index. +- Genericized taxonomy, cross-project signals. + +## [1.0.0] + +### Added +- Initial release with `/remember` and `/recall`. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..9eea4e5 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,45 @@ +# Contributor Covenant Code of Conduct + +## Our pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our standards + +Examples of behavior that contributes to a positive environment: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +- Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior: + +- The use of sexualized language or imagery, and sexual attention or advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others’ private information, such as a physical or email address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issue tickets, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at **conduct@brightwayai.com** (or via GitHub to maintainers of this repository if you prefer). All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at . diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9af54d9 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,76 @@ +# Contributing to Session Memory Plugin + +Thanks for your interest in improving session memory! This guide covers what you need to know before submitting a PR. + +## How the repo is organized + +``` +commands/ Cowork (Claude Desktop) command files — loaded by the plugin system +skills/ Cowork skill files — auto-fire versions of commands +.claude-plugin/ Plugin metadata (plugin.json) +.github/ CI workflows, issue/PR templates +docs/ Architecture notes +``` + +Every command in `commands/` has a matching skill in `skills/`. If you change a command's behavior, update its skill counterpart too. + +## Development workflow + +1. **Fork** the repo and create a feature branch from `main`. +2. Make your changes (see guidelines below). +3. Open a PR against `BrightWayAI/session-memory-plugin:main`. + +## What to check before submitting + +- [ ] **Command ↔ skill parity** — changes to a command file are reflected in the corresponding skill. +- [ ] **`plugin.json` version** — bump the version in `.claude-plugin/plugin.json` when your change is user-visible (new command, behavior change, storage format change). Patch for fixes, minor for features. +- [ ] **README** — if you add or change a command, update the README command table and changelog section. +- [ ] **CHANGELOG.md** — add an entry under `## [Unreleased]` describing your change. +- [ ] **Frontmatter** — every command and skill file starts with YAML frontmatter (`---` delimiters) containing at least a `description` field. Keep it accurate. + +## Writing command files + +Command files are markdown instructions that Claude follows at runtime. They are **not** traditional code. A few conventions: + +- **Step-numbered structure** — use `## Step N — Title` headings so Claude can follow sequentially. +- **Storage path** — memory lives at `~/Documents/Claude/memory/`. Never hardcode an absolute path; use `~` or `%USERPROFILE%` with a note for cross-platform users. +- **Cowork directory access** — `commands/` files may call `mcp__cowork__request_cowork_directory` for folder mounting. This tool only exists in Cowork. Do not add it to `.claude/commands/` files (Claude Code has native fs access). +- **No fabrication** — commands should never tell Claude to make up memory. Only commit what was actually discussed. + +## Commit messages + +Use a short prefix: + +| Prefix | When | +|--------|------| +| `feat:` | New command, skill, or user-visible behavior | +| `fix:` | Bug fix or correction | +| `docs:` | README, CHANGELOG, CONTRIBUTING, architecture docs | +| `chore:` | CI, templates, metadata, repo hygiene | + +Example: `feat(remember): add git-aware context capture (Step 1b)` + +## Local checks + +Before opening a PR, run the same validation as CI: + +```bash +python3 scripts/check_repo.py +``` + +This verifies `plugin.json` parses and that every `commands/*.md` and `skills/*/SKILL.md` file has valid YAML frontmatter with a `description` field. + +## Reporting issues + +Use the issue templates: + +- **Bug report** — include which platform (Cowork / Claude Code), which command, and what you expected vs. what happened. +- **Feature request** — describe the use case and which command or workflow it affects. + +## Code of conduct + +This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). Be kind, be constructive. + +## Questions? + +Open a Discussion or tag the maintainers in an issue. We're happy to help you get started. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..9abb050 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 BrightWay AI + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 6c59bd4..776743a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,7 @@ -# Session Memory Plugin v3.0 +# Session Memory Plugin v3.0.1 + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![CI](https://github.com/BrightWayAI/session-memory-plugin/actions/workflows/validate.yml/badge.svg)](https://github.com/BrightWayAI/session-memory-plugin/actions/workflows/validate.yml) **Build persistent intelligence — project state AND knowledge — across your working world.** @@ -288,12 +291,18 @@ Chat doesn't have file access or a plugin system. Memory can't persist automatic --- +## For contributors + +Contributions are welcome. Start with **[CONTRIBUTING.md](CONTRIBUTING.md)** (workflow, command/skill parity, versioning) and **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** (how the pieces fit together). Please read the **[Code of Conduct](CODE_OF_CONDUCT.md)**. Security-sensitive reports belong in **[SECURITY.md](SECURITY.md)**. Full release history: **[CHANGELOG.md](CHANGELOG.md)**. + +--- + ## Changelog -### v3.1.0 -- **Git-aware memory**: `/remember` now captures branch, recent commits, and uncommitted changes for code-focused sessions -- **Cross-platform paths**: Windows path guidance (`%USERPROFILE%\Documents\Claude\memory\`) documented alongside Unix paths -- **Shared memory across platforms**: Cowork and Claude Code use the same storage path, enabling seamless cross-platform workflows +See **[CHANGELOG.md](CHANGELOG.md)** for the complete version history. Summary below: + +### v3.0.1 +- Open source hygiene: `LICENSE`, contributing guides, templates, security policy, architecture doc, and CI validation for `plugin.json` and markdown frontmatter. ### v3.0.0 - **File-based storage**: Memory now persists to `~/Documents/Claude/memory/` as markdown files diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..a622f7f --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,34 @@ +# Security Policy + +## What this plugin does with your filesystem + +Session Memory reads and writes **plain-text markdown files** in a single directory on your computer: + +``` +~/Documents/Claude/memory/ +``` + +(On Windows: `%USERPROFILE%\Documents\Claude\memory\`) + +It does **not**: +- Access files outside this directory. +- Send data to any remote server. +- Execute code or scripts. + +All memory files are human-readable markdown. You can inspect, edit, move, or delete them at any time. + +## Supported versions + +| Version | Supported | +|---------|-----------| +| 3.x | Yes | +| < 3.0 | No | + +## Reporting a vulnerability + +If you discover a security issue — for example, a command file that could be manipulated to read or write outside the expected memory directory — please report it **privately**: + +1. **GitHub private vulnerability reporting**: Go to the repo's **Security** tab → **Report a vulnerability**. +2. **Email**: security@brightwayai.com + +Please **do not** open a public issue for security problems. We will acknowledge reports within 72 hours and aim to publish a fix within 7 days for confirmed issues. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..567297b --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -0,0 +1,51 @@ +# Architecture + +Session Memory is a **markdown-instruction plugin**: there is no runtime binary. Claude reads command and skill files as prompts, then reads and writes files under a single memory directory on disk. + +## High-level flow + +``` +User invokes /remember (or a skill auto-fires) + │ + ▼ +Cowork loads commands/.md OR Claude Code loads .claude/commands/.md + │ + ▼ +Claude follows step-by-step instructions (extract state, format entries, write files) + │ + ▼ +Filesystem: ~/Documents/Claude/memory/ + ├── DASHBOARD.md ← master index + ├── / ← e.g. client/, strategy/ + │ └── .md ← one file per node id + └── archive/ ← archived nodes +``` + +## Repository layout + +| Path | Role | +|------|------| +| `commands/*.md` | Cowork slash commands. May reference Cowork-only directory tools. | +| `skills/*/SKILL.md` | Cowork skills: natural-language triggers that mirror command behavior. | +| `.claude-plugin/plugin.json` | Plugin name, version, description for the Cowork marketplace. | +| `.claude/commands/*.md` | Optional Claude Code copies of commands (no Cowork MCP calls). | + +Every command has a **paired skill** with aligned behavior so “save this” and `/remember` stay consistent. + +## Memory model + +- **Node** — A logical project or theme (e.g. `client:acme-corp`, `strategy:pricing`). Maps to one markdown file under `memory/`. +- **Living summary** — Replaced each session; short status for the node. +- **Changelog (`LOG`)** — Append-only lines per session. +- **Knowledge entries** — INSIGHT, LESSON, MODEL, GOTCHA, RECIPE, CORRECTION; highest long-term value. +- **DASHBOARD.md** — Aggregates active nodes, P0 actions, recent knowledge, and stale-thread hints for fast `/recall` with no arguments. + +## Versioning and releases + +- **Version** lives in `.claude-plugin/plugin.json` and should match release tags and [CHANGELOG.md](../CHANGELOG.md). +- Pushing to `main` may trigger downstream marketplace notification (see `.github/workflows/notify-marketplace.yml`); coordinate with maintainers before merging release-sensitive changes. + +## Further reading + +- [CONTRIBUTING.md](../CONTRIBUTING.md) — how to change commands, parity rules, and PR checklist. +- [SECURITY.md](../SECURITY.md) — filesystem scope and how to report issues. diff --git a/scripts/check_repo.py b/scripts/check_repo.py new file mode 100644 index 0000000..144b712 --- /dev/null +++ b/scripts/check_repo.py @@ -0,0 +1,65 @@ +#!/usr/bin/env python3 +"""Validate plugin.json and YAML frontmatter on command/skill files.""" +from __future__ import annotations + +import json +import re +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent + + +def main() -> int: + plugin_path = ROOT / ".claude-plugin" / "plugin.json" + try: + data = json.loads(plugin_path.read_text(encoding="utf-8")) + except (json.JSONDecodeError, OSError) as e: + print(f"ERROR: invalid plugin.json: {e}", file=sys.stderr) + return 1 + + required = ("name", "version", "description", "license") + missing = [k for k in required if k not in data] + if missing: + print(f"ERROR: plugin.json missing keys: {missing}", file=sys.stderr) + return 1 + + checked = 0 + errors = 0 + + for path in sorted((ROOT / "commands").glob("*.md")): + errors += check_markdown(path) + checked += 1 + + for path in sorted((ROOT / "skills").glob("*/SKILL.md")): + errors += check_markdown(path) + checked += 1 + + claude_cmds = ROOT / ".claude" / "commands" + if claude_cmds.is_dir(): + for path in sorted(claude_cmds.glob("*.md")): + errors += check_markdown(path) + checked += 1 + + print(f"OK: plugin.json valid; {checked} markdown files checked.") + return 1 if errors else 0 + + +def check_markdown(path: Path) -> int: + text = path.read_text(encoding="utf-8") + if not text.startswith("---\n"): + print(f"ERROR: {path.relative_to(ROOT)}: must start with YAML frontmatter (---)", file=sys.stderr) + return 1 + end = text.find("\n---\n", 4) + if end == -1: + print(f"ERROR: {path.relative_to(ROOT)}: unclosed frontmatter", file=sys.stderr) + return 1 + front = text[4:end] + if not re.search(r"^description:\s*.+", front, re.MULTILINE): + print(f"ERROR: {path.relative_to(ROOT)}: frontmatter must include non-empty description", file=sys.stderr) + return 1 + return 0 + + +if __name__ == "__main__": + sys.exit(main())