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

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 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):

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.

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

# 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:

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)

npm install -D dependency-cruiser husky lint-staged

Python (example)

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

License

Licensed under the MIT License — see 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

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

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

快速开始

本地克隆 / 拷贝

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 分发与更新

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，与 package.json 中的 license 字段一致。