npm package: @memtensor/memos-harness-template
Description: MemOS-oriented Harness scaffold for AI coding agents: AGENTS.md / CLAUDE.md / CODEX.md, Cursor rules, design docs (core-beliefs, ADR, delivery SOP), dependency-cruiser, Husky, freshness & CI scripts. Non-interactive npm CLI copies templates and prints an 
Latest version: 0.1.0

# memos-harness-template

**Scaffold for an AI-agent Harness** (three layers × three dimensions): navigation for agents, IDE rules, design docs, and lightweight automation so coding agents stay inside architecture and documentation does not rot.

Repository: [github.com/syzsunshine219/memos-harness-template](https://github.com/syzsunshine219/memos-harness-template)

**Maintainers (GitHub About / Topics / default branch / MIT badge)**

Use the **website** (no CLI required):

1. Open the repo on GitHub → right sidebar **About** → click the **gear** (Edit repository details).
2. Paste the **English (short)** description from the section below into the description field.
3. Under **Topics**, add: `harness`, `cursor`, `memos`, `ai-agent`, `template`.
4. **Settings** → **General** → **Default branch** → ensure it is **`main`** (change only if yours is different).

The root [`LICENSE`](LICENSE) file is standard MIT text on `main`; GitHub usually shows **MIT** on the About sidebar after indexing—no separate “choose license” step.

**Optional — REST API** (PAT with `repo` scope; do not commit the token):

```bash
export GITHUB_TOKEN='your_token_here'
OWNER=syzsunshine219
REPO=memos-harness-template
DESC='MemOS-oriented Harness template for AI coding agents: AGENTS/CLAUDE/CODEX, Cursor rules, design docs (core-beliefs, ADR, delivery SOP), dependency-cruiser, Husky, freshness & affected-test scripts. Non-interactive npx CLI; MIT.'

curl -sS -X PATCH \
  -H "Authorization: Bearer $GITHUB_TOKEN" -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/$OWNER/$REPO" \
  -d "{\"description\":$(printf '%s' "$DESC" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}"

curl -sS -X PATCH \
  -H "Authorization: Bearer $GITHUB_TOKEN" -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/$OWNER/$REPO" \
  -d '{"default_branch":"main"}'

curl -sS -X PUT \
  -H "Authorization: Bearer $GITHUB_TOKEN" -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/$OWNER/$REPO/topics" \
  -d '{"names":["harness","cursor","memos","ai-agent","template"]}'
```

The first `curl` only updates `description`; the second sets `default_branch`; the third sets topics. Combine carefully if your shell struggles with quoting—use the **website** instead.

This template is **MemOS-oriented**: optional rules cover MemOS memory context (`mem-context.mdc`). It pairs well with MemOS-based agents and plugins (for example OpenClaw local/cloud flows). Upstream project: **[MemTensor/MemOS](https://github.com/MemTensor/MemOS)**.

### Description (copy for GitHub “About” / npm)

**English (short, ~350 chars max for GitHub):**

> MemOS-oriented Harness template for AI coding agents: AGENTS/CLAUDE/CODEX, Cursor rules, design docs (core-beliefs, ADR, delivery SOP), dependency-cruiser, Husky, freshness & affected-test scripts. Non-interactive `npx` CLI; MIT.

**中文（仓库简介 / 一句话）：**

> 面向 MemOS 生态的 AI Agent Harness 脚手架：三层×三维度文档与规则、可选 MemOS 记忆上下文、依赖与提交门禁、保鲜脚本；`npx` 非交互拷贝模板并输出 Agent 初始化 Prompt；MIT 协议。

---

## Quick start

### Clone / copy locally

```bash
# Copy template files + print the Agent prompt
bash /path/to/memos-harness-template/init.sh /path/to/your/project

# Prompt only (no file copy)
bash /path/to/memos-harness-template/init.sh /path/to/your/project --dry
```

### npm (recommended for teams)

Publish to a private registry, GitHub Packages, or the public npm registry, then:

```bash
npx @memtensor/memos-harness-template@latest /path/to/your/project

# Or pin a version
npm install -D @memtensor/memos-harness-template@latest
npx @memtensor/memos-harness-template /path/to/your/project
```

After upgrading the package, run `npx @memtensor/memos-harness-template …` again to pick up **new** template paths. **Existing files are skipped by default** (no overwrite); re-aligning customized files is a manual diff/merge.

The package is published on the public registry as **`@memtensor/memos-harness-template`** (MemTensor npm org, `publishConfig.access: public` in `package.json`).

Before publishing: `npm pack --dry-run` to verify packaged files.

The flow is **non-interactive**: after copying **14** template files, the CLI prints a **prompt** you paste into Cursor or Claude Code so an agent fills `{{placeholders}}`.

**Note:** the CLI shells out to **bash** (macOS/Linux out of the box; on Windows use Git Bash or WSL).

---

## Repository layout

```
memos-harness-template/
├── README.md
├── init.sh
├── AGENTS.md                    # L1: agent map
├── CLAUDE.md                    # L1: Claude Code entry + inlined constraints
├── CODEX.md                     # L1: Codex entry + inlined constraints
├── .cursor/rules/
│   ├── project-dev.mdc          # L1: dependency / security / style rules
│   ├── mem-context.mdc          # L1: MemOS context (optional)
│   └── harness-maintenance.mdc  # L1 × entropy: doc sync reminders
├── .dependency-cruiser.cjs      # L3 × constraints: dependency boundaries
├── .husky/commit-msg            # L3 × constraints: commit message check
├── docs/
│   ├── design-docs/
│   │   ├── core-beliefs.md
│   │   ├── api-conventions.md
│   │   └── adr-template.md
│   └── delivery-sop.md
├── scripts/
│   ├── ci-affected-tests.sh
│   └── check-harness-freshness.sh
├── bin/harness-init.cjs
├── package.json
└── package.json.snippet         # merge into the target Node project
```

---

## Three dimensions × three layers

|  | Context engineering | Architectural constraints | Entropy management |
|--|---------------------|---------------------------|--------------------|
| **L1 Injection** | Rules / AGENTS · CLAUDE · CODEX | Rules: forbidden patterns | Sync reminders; avoid stale hard-coded counts |
| **L2 Knowledge** | Scenario-triggered `docs/` | `core-beliefs`, ADRs | Freshness checklists; monthly audit prompts |
| **L3 Execution** | MemOS / tool context | dep-cruiser, CI hooks, spec gates | Freshness scripts; drift signals |

---

## Placeholders

Templates use `{{PLACEHOLDER}}` markers, for example:

| Placeholder | Meaning | Example |
|-------------|---------|---------|
| `{{PROJECT_NAME}}` | Project name | memos-local-openclaw |
| `{{PROJECT_DESCRIPTION}}` | One-line description | OpenClaw on-device memory plugin |
| `{{TECH_STACK}}` | Stack | TypeScript, SQLite, FTS5 |
| `{{BUILD_CMD}}` / `{{DEV_CMD}}` / `{{TEST_CMD}}` / `{{LINT_CMD}}` | Commands | `npm run build` … |
| `{{TEST_FRAMEWORK}}` | Test runner | vitest / pytest |
| `{{TEST_DIR}}` | Tests directory | `tests/` |
| `{{MAIN_ENTRY}}` | Main entry | `index.ts` |
| `{{PUBLISH_CMD}}` | Release path | GitHub Actions / `npm publish` |

---

## Customization checklist

**Must tailor to your repo**

1. `AGENTS.md` — real module map and ownership  
2. `.cursor/rules/project-dev.mdc` — dependency and security rules  
3. `docs/design-docs/core-beliefs.md` — non-negotiable principles + test gates  
4. `.dependency-cruiser.cjs` — boundary rules  
5. `scripts/ci-affected-tests.sh` — changed paths → tests  

**Optional**

- `mem-context.mdc` — only if you use MemOS-style memory tools  
- `api-conventions.md` — only if you expose HTTP APIs  
- `package.json.snippet` — Node.js projects only  

**Node dev dependencies (example)**

```bash
npm install -D dependency-cruiser husky lint-staged
```

**Python (example)**

```bash
pip install pre-commit import-linter
# replace dependency-cruiser with import-linter or similar
```

---

## License

Licensed under the **MIT License** — see [LICENSE](LICENSE). This matches the `license` field in `package.json`.

---

---

# 中文说明

**memos-harness-template** 是面向 AI 编程助手的 **Harness 脚手架**（三层 × 三维度）：Agent 导航、IDE 规则、设计文档与轻量自动化，让 Agent 在架构边界内工作，并降低文档随时间腐化。

**项目描述**：可复制英文节「Description (copy for GitHub “About” / npm)」中的中英文到 GitHub 仓库 About 或内部文档；npm 包摘要见 `package.json` 的 `description` 字段。

源码仓库：[github.com/syzsunshine219/memos-harness-template](https://github.com/syzsunshine219/memos-harness-template)

**维护者**：在 GitHub 网页打开本仓库 → 右侧 **About** 齿轮 → 粘贴上文 **English (short)** 描述 → Topics 填 `harness`、`cursor`、`memos`、`ai-agent`、`template` → **Settings → General → Default branch** 设为 **`main`**。根目录已有 [`LICENSE`](LICENSE)，一般会显示 **MIT**。详见上文英文 **Maintainers** 小节（含可选 `curl` + PAT）。

本模板 **面向 MemOS 生态**：可选规则包含 MemOS 记忆上下文（`mem-context.mdc`），与基于 MemOS 的 Agent / 插件（例如 OpenClaw 本地/云端场景）配合使用。上游主项目为 **[MemTensor/MemOS](https://github.com/MemTensor/MemOS)**。

---

## 快速开始

### 本地克隆 / 拷贝

```bash
bash /path/to/memos-harness-template/init.sh /path/to/your/project
bash /path/to/memos-harness-template/init.sh /path/to/your/project --dry
```

### 通过 npm 分发与更新

```bash
npx @memtensor/memos-harness-template@latest /path/to/your/project
npm install -D @memtensor/memos-harness-template@latest
npx @memtensor/memos-harness-template /path/to/your/project
```

升级包后再执行 `npx @memtensor/memos-harness-template …` 可拿到**新增**模板文件；**已存在路径默认 SKIP 不覆盖**。npm 包名为 **`@memtensor/memos-harness-template`**（memtensor 组织下 public scoped 包）。

发布前：`npm pack --dry-run`。

流程**非交互**：拷贝约 **14** 个文件后输出 **Prompt**，粘贴到 Cursor / Claude Code，由 Agent 填充 `{{占位符}}`。

**说明**：CLI 依赖本机 **bash**（Windows 请用 Git Bash / WSL）。

---

## 模板结构

见上文英文 **Repository layout** 代码块（与本地 `memos-harness-template/` 目录一致）。

---

## 三维度 × 三层架构

|  | 上下文工程 | 架构约束 | 熵管理 |
|--|----------|---------|--------|
| **L1 注入** | Rules / AGENTS·CLAUDE·CODEX | Rules 禁止项 | 同步提醒 / 去硬编码 |
| **L2 知识** | docs/ 按场景读取 | core-beliefs / ADR | 保鲜清单 / 月度审计 Prompt |
| **L3 执行** | MemOS 等工具上下文 | dep-cruiser / CI hooks | 保鲜脚本 / 漂移信号 |

---

## 占位符说明

见上文英文 **Placeholders** 表格（`{{PROJECT_NAME}}` 等）。

---

## 定制指南

**必须按项目修改**：`AGENTS.md`、`project-dev.mdc`、`core-beliefs.md`、`.dependency-cruiser.cjs`、`ci-affected-tests.sh`。

**可选**：`mem-context.mdc`（MemOS）、`api-conventions.md`（HTTP API）、`package.json.snippet`（Node）。

Node / Python 依赖安装示例见英文 **Customization checklist**。

---

## 许可说明

采用 **MIT 许可证**，全文见仓库根目录 [LICENSE](LICENSE)，与 `package.json` 中的 `license` 字段一致。