basicmachines-co · tyler555g · Apr 19, 2026 · Apr 19, 2026 · Apr 19, 2026 · Apr 19, 2026
diff --git a/.changeset/README.md b/.changeset/README.md
@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).
diff --git a/.changeset/add-copilot-cli-support.md b/.changeset/add-copilot-cli-support.md
@@ -0,0 +1,10 @@
+---
+"basic-memory-skills": minor
+---
+
+feat: add GitHub Copilot CLI support and 12-factor agent improvements
+
+- Added GitHub Copilot CLI as a supported agent target (~/.copilot/skills)
+- Applied 12-Factor Agents principles (https://github.com/humanlayer/12-factor-agents) to all 10 SKILL.md files
+- Added npm postinstall script supporting Copilot CLI, Claude Code, and future agents
+- Updated README with npm install instructions and compatible agents section
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
 .DS_Store
 .idea/
 moby-dick.txt
+node_modules/
diff --git a/.mcp.json b/.mcp.json
@@ -1,14 +1,9 @@
 {
   "mcpServers": {
     "basic-memory": {
-      "command": "uv",
-      "args": [
-        "--directory",
-        "/Users/phernandez/dev/basicmachines/basic-memory",
-        "run",
-        "src/basic_memory/cli/main.py",
-        "mcp"
-      ]
+      "command": "uvx",
+      "args": ["basic-memory", "mcp"],
+      "env": {}
     }
   }
-}
+}
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -6,25 +6,31 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Skills collection for [Basic Memory](https://github.com/basicmachines-co/basic-memory) — a local-first knowledge graph built on markdown files and MCP. Each skill teaches AI assistants how to effectively use Basic Memory's MCP tools.
 
-Skills can be installed via `npx skills add` or copied manually into any agent's skills directory.
+Skills can be installed via `npm install -g basic-memory-skills`, `npx skills add`, or copied manually into any agent's skills directory.
 
 ## Repository Structure
 
 Each skill is a single `SKILL.md` file in its own directory:
 
 ```
-memory-tasks/SKILL.md           # Task tracking across context compaction
-memory-schema/SKILL.md          # Schema lifecycle (discover, infer, validate, drift)
-memory-reflect/SKILL.md         # Sleep-time memory consolidation
-memory-notes/SKILL.md           # Note writing patterns and knowledge graph design
-memory-defrag/SKILL.md          # Memory reorganization and cleanup
-memory-metadata-search/SKILL.md # Structured metadata filtering and queries
-memory-lifecycle/SKILL.md       # Entity status transitions and folder-based archival
-memory-ingest/SKILL.md          # Process external input into structured entities
-memory-research/SKILL.md        # Web research synthesized into Basic Memory entities
+memory-tasks/SKILL.md                # Task tracking across context compaction
+memory-schema/SKILL.md               # Schema lifecycle (discover, infer, validate, drift)
+memory-reflect/SKILL.md              # Sleep-time memory consolidation
+memory-notes/SKILL.md                # Note writing patterns and knowledge graph design
+memory-defrag/SKILL.md               # Memory reorganization and cleanup
+memory-metadata-search/SKILL.md      # Structured metadata filtering and queries
+memory-lifecycle/SKILL.md            # Entity status transitions and folder-based archival
+memory-ingest/SKILL.md               # Process external input into structured entities
+memory-research/SKILL.md             # Web research synthesized into Basic Memory entities
+memory-literary-analysis/SKILL.md    # Literary analysis into structured knowledge graph
 ```
 
-There is no code to build, lint, or test — this is a pure markdown project.
+Infrastructure files:
+- `package.json` — npm package definition with postinstall script
+- `scripts/postinstall.js` — copies skills to agent directories on `npm install -g`
+- `.changeset/` — changeset config and pending changesets
+- `commitlint.config.js` — enforces [Conventional Commits](https://www.conventionalcommits.org)
+- `skills-lock.json` — Skills CLI lock file (auto-generated)
 
 ## SKILL.md Format
 
@@ -44,8 +50,15 @@ description: "What the skill does and when to use it."
 ## Adding a New Skill
 
 1. Create `memory-<name>/SKILL.md` with frontmatter and markdown instructions
-2. Update `README.md` with the new skill's summary
-3. Commit and push
+2. Add the skill directory to the `files` array in `package.json`
+3. Add the skill name to the `SKILLS` array in `scripts/postinstall.js`
+4. Update `README.md` with the new skill's summary
+5. Create a changeset: `npx changeset`
+6. Commit using [Conventional Commits](https://www.conventionalcommits.org): `feat(memory-<name>): add <description>`
+
+## Commit Conventions
+
+All commits follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) enforced by commitlint. Common types: `feat:`, `fix:`, `docs:`, `chore:`.
 
 ## Key Concepts Referenced in Skills
 

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -4,25 +4,57 @@
 
 ```
 basic-memory-skills/
-├── memory-tasks/SKILL.md           # Task tracking skill
-├── memory-schema/SKILL.md          # Schema lifecycle skill
-├── memory-reflect/SKILL.md         # Memory consolidation skill
-├── memory-notes/SKILL.md           # Note writing patterns skill
-├── memory-defrag/SKILL.md          # Memory cleanup skill
-├── memory-metadata-search/SKILL.md # Metadata search skill
-├── memory-lifecycle/SKILL.md       # Entity lifecycle skill
-├── memory-ingest/SKILL.md          # External input processing skill
-├── memory-research/SKILL.md        # Web research skill
+├── memory-tasks/SKILL.md                # Task tracking skill
+├── memory-schema/SKILL.md               # Schema lifecycle skill
+├── memory-reflect/SKILL.md              # Memory consolidation skill
+├── memory-notes/SKILL.md                # Note writing patterns skill
+├── memory-defrag/SKILL.md               # Memory cleanup skill
+├── memory-metadata-search/SKILL.md      # Metadata search skill
+├── memory-lifecycle/SKILL.md            # Entity lifecycle skill
+├── memory-ingest/SKILL.md               # External input processing skill
+├── memory-research/SKILL.md             # Web research skill
+├── memory-literary-analysis/SKILL.md    # Literary analysis skill
+├── scripts/postinstall.js               # npm postinstall — copies skills to agent dirs
+├── .changeset/                          # Changeset config and pending changesets
+├── package.json                         # npm package definition
+├── commitlint.config.js                 # Conventional Commits enforcement
+├── skills-lock.json                     # Skills CLI lock file (auto-generated)
+├── CLAUDE.md                            # Claude Code agent guidance
+├── AGENTS.md                            # Agent guidance pointer
+├── .mcp.json                            # MCP server configuration
+├── DEVELOPMENT.md                       # This file
 └── README.md
 ```
 
 Each skill is a single `SKILL.md` file with YAML frontmatter (`name`, `description`) and markdown instructions.
 
 ## Testing Skills Locally
 
+### Via npm (recommended)
+
+Install the package globally to auto-deploy skills to all supported agent directories:
+
+```bash
+npm install -g basic-memory-skills
+```
+
+The postinstall script copies skills to `~/.copilot/skills/`, `~/.claude/skills/`, and `~/.agents/skills/` (whichever exist). Then reload in your agent:
+
+```
+# GitHub Copilot CLI
+/skills reload
+
+# Claude Code — restart your session
+```
+
+### Manual copy
+
 Copy a skill into your agent's skills directory and start a new session:
 
 ```bash
+# GitHub Copilot CLI — global
+cp -r memory-tasks ~/.copilot/skills/
+
 # Claude Code — global
 cp -r memory-tasks ~/.claude/skills/
 
@@ -55,8 +87,47 @@ npx skills add basicmachines-co/basic-memory-skills --agent claude
 1. Create a new directory: `memory-<name>/SKILL.md`
 2. Add YAML frontmatter with `name` and `description`
 3. Write skill instructions in markdown
-4. Update `README.md` with the new skill's summary
-5. Commit and push
+4. Add the skill directory to the `files` array in `package.json`
+5. Add the skill name to the `SKILLS` array in `scripts/postinstall.js`
+6. Update `README.md` with the new skill's summary
+7. Create a changeset: `npx changeset` (select `minor` for new skills)
+8. Commit and push
+
+## Commit Conventions
+
+All commits follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/). A [commitlint](https://github.com/conventional-changelog/commitlint) configuration is included — run `npx commitlint --edit` to validate commit messages locally.
+
+```
+<type>[optional scope]: <description>
+```
+
+Common types:
+- `feat:` — new skill or feature (minor version bump)
+- `fix:` — bug fix (patch version bump)
+- `docs:` — documentation only
+- `chore:` — build, tooling, maintenance
+
+Examples:
+```
+feat(memory-tasks): add pause/resume protocol
+fix(postinstall): handle missing ~/.copilot directory
+docs: update DEVELOPMENT.md with commit conventions
+```
+
+## Changesets
+
+[Changesets](https://github.com/changesets/changesets) track what changed and at what version level for every PR:
+
+```bash
+# After making changes, create a changeset
+npx changeset
+
+# On release, bump versions and generate changelog
+npx changeset version
+
+# Publish
+npx changeset publish
+```
 
 ## OpenClaw Plugin Integration
 

diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 basicmachines-co
+
+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.