diff --git a/.agent/project.yaml b/.agent/project.yaml new file mode 100644 index 0000000..e02a733 --- /dev/null +++ b/.agent/project.yaml @@ -0,0 +1,41 @@ +project: + name: agent-memory-kit + description: a vendored, markdown-first project memory kit for coding agents +architecture: + file: docs/planning/vision.md +conventions: + - Keep agent-memory-kit repo-local and markdown-first; do not add daemons, databases, dashboards, MCP servers, or telemetry. + - Generated files must remain reproducible from generate.py, adapters, templates, and .agent/project.yaml. +agents: + claude_code: + enabled: false + codex: + enabled: true + hermes: + enabled: true + openclaw: + enabled: false + cursor: + enabled: false + windsurf: + enabled: false + gemini_cli: + enabled: false + antigravity: + enabled: false +memory: + semantic_max_lines: 500 + working_max_lines: 300 + capture_at: + - response + - merge + files: + semantic: memory/semantic.md + working: memory/working.md + decisions: DECISIONS.md + candidates: memory/candidates.md + candidates_rejected: memory/candidates.rejected.md + approval_mode: + default: auto + review: [] + task_directory: dev/[task]/ diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..4a558e4 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,29 @@ +name: CI + +on: + pull_request: + push: + branches: + - main + +jobs: + test: + runs-on: ubuntu-latest + + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install test dependencies + run: python3 -m pip install pytest pyyaml + + - name: Run tests + run: python3 -m pytest -q + + - name: Check generated files + run: python3 generate.py all . --check diff --git a/.gitignore b/.gitignore index fe22d4c..5c87458 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ __pycache__/ .agent/.generated_state.json .agent/eval/ docs/planning/ +memory/working.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e511d2c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,85 @@ +# Project Context — agent-memory-kit + +**agent-memory-kit** is a vendored, markdown-first project memory kit for coding agents + + + +## Memory System + +This project uses a file-based memory system to maintain context across sessions. + +### On Session Start + +Read `memory/semantic.md` ONCE to load project context before answering. + +### On Every Turn + +The preprompt hook handles reading `memory/working.md`. + +### Task Files + +Only load `/dev/[task]/*` files when actively working on that task. + +### MCP Efficiency + +Before calling any MCP tool to retrieve information, first check if that information might exist in `memory/semantic.md` or `dev/[task]/context.md` — local files are cheaper than remote MCP queries. + +### Keep Context Minimal + +Do not speculatively load files "just in case". + +### Mid-Session Drift + +If reasoning becomes uncertain or inconsistent with prior context, re-read `memory/semantic.md` before continuing. + +### Memory Discipline + +- `memory/semantic.md` — current build state; update directly after changes; summarize what you changed +- `memory/working.md` — live task state; update freely after each response; no approval needed +- `DECISIONS.md` — append-only log of architectural decisions; update directly after changes; summarize new entries +- `dev/[task]/context.md` — log confirmed assumptions immediately; no approval needed +- `memory/candidates.md` — staged lessons awaiting promotion; append-only, one heading per claim; append candidate claims with source pointers; never edit existing entries +- `docs/planning/vision.md` — principles, load-bearing assumptions, planned capabilities; update only on merge when a capability ships or an assumption is invalidated; **never put current state here** (that's `semantic.md`), **never put planning details here** (tickets, checklists, phases) +- `memory/candidates.rejected.md` — promoted-by-move from candidates.md; each entry includes a Why rejected: reason; move entries from candidates.md with Why rejected: appended + +**DECISIONS.md vs. Assumptions distinction:** +- `DECISIONS.md` = immutable log — "we chose X on date Y because Z" — never edited, only superseded by appending +- `docs/planning/vision.md` Assumptions = live load-bearing premises — mutable; when invalidated, append a supersession to `DECISIONS.md` first, then update the assumption + +**On PR merge:** check `docs/planning/vision.md` — move shipped capabilities to `memory/semantic.md` and remove them from the Vision section; append a supersession to `DECISIONS.md` then update or remove any invalidated Assumption. + +**Stage → Graduate promotion (#11):** +- `memory/candidates.md` — append-only staging queue. Each entry is a `###` heading claim with a `- Staged: YYYY-MM-DD` date and a `- Sources:` bullet list (commit hashes, session refs, or file:line pointers). Before appending, grep candidates.md for matching claims — if found, append a source bullet to the existing heading instead of creating a duplicate. One heading per claim. +- `memory/semantic.md` — on promotion, move the entire heading block from candidates.md into semantic.md with a one-line `**Why accepted:**` rationale appended. The candidate entry disappears from candidates.md. +- `memory/candidates.rejected.md` — on rejection, move the heading block here with a one-line `**Why rejected:**` reason. Preserves the churn history to prevent re-litigation. +- All promotions and rejections are committed separately with `promote:` or `reject:` commit message prefixes. The diff *is* the audit trail. + +--- + +## Architecture + +Before implementing a feature, read `docs/planning/vision.md`. It is the canonical record of architectural principles, load-bearing assumptions, and planned capabilities — not current build state (that lives in `memory/semantic.md`). + + +--- + +## Key conventions + +- Keep agent-memory-kit repo-local and markdown-first; do not add daemons, databases, dashboards, MCP servers, or telemetry. +- Generated files must remain reproducible from generate.py, adapters, templates, and .agent/project.yaml. + +--- + +## Optional: Hermes Memory Mirroring + +Hermes has its own `MEMORY.md` / `USER.md` persistence layer. These are complementary, +not replacements, for this project's `memory/` files. If you want high-signal lessons +visible inside Hermes's built-in persistence, you can symlink: + +```bash +ln -s memory/semantic.md MEMORY.md +``` + +The project's `memory/semantic.md` remains the single source of truth. + + diff --git a/DECISIONS.md b/DECISIONS.md new file mode 100644 index 0000000..7d2528a --- /dev/null +++ b/DECISIONS.md @@ -0,0 +1,13 @@ +# Decisions — agent-memory-kit + +## 2026-05-12 — CI Gate For Generated-File Drift + +**Decision:** Add CI that runs the test suite and `python3 generate.py all . --check` against the kit repo's own generated `AGENTS.md`. + +**Reasoning:** The applycling audit found a real failure mode: generated entrypoints can be manually corrected while the generator source remains stale. A prose closeout rule helps, but CI is the enforcement mechanism that prevents stale generated output from merging unnoticed. + +**Trade-offs:** The kit repo now carries a minimal `.agent/project.yaml`, `AGENTS.md`, and tracked memory files for itself. That is a small amount of self-dogfood state, but it gives CI a real generated artifact to compare against without introducing any daemon, database, or non-markdown state. + +**When to revisit:** If the generated surface grows too large for the kit repo itself, move the self-check target to a tracked fixture project and run `generate.py all --check` instead. + +**Affects:** `.github/workflows/ci.yml`, `.agent/project.yaml`, `AGENTS.md`, `memory/semantic.md`, `DECISIONS.md` diff --git a/README.md b/README.md index 9739ad8..e3ea11f 100644 --- a/README.md +++ b/README.md @@ -142,6 +142,20 @@ python .agent/memory-kit/generate.py all For 1–5 repos, copy-paste is faster than any automation. +## CI + +This repository runs a small CI gate on pull requests and pushes to `main`: + +```bash +python3 -m pytest -q +python3 generate.py all . --check +``` + +The second command checks that the kit repo's generated `AGENTS.md` is still +reproducible from `generate.py`, `adapters/`, `templates/`, and +`.agent/project.yaml`. If generated output drifts, update the source config or +template first, then regenerate. + --- ## What we explicitly don't build diff --git a/memory/candidates.md b/memory/candidates.md new file mode 100644 index 0000000..7d4f6e4 --- /dev/null +++ b/memory/candidates.md @@ -0,0 +1,17 @@ +# Candidate Lessons + +Claims that have recurred across sessions but have not yet been promoted to +semantic.md with a `**Why accepted:**` rationale. + +Format: + +```md +### claim heading +- Staged: YYYY-MM-DD +- Sources: + - , , or +``` + +Before appending a new claim, search this file for a near-duplicate heading. +On promotion, move the full heading block to `memory/semantic.md`. +On rejection, move the full heading block to `memory/candidates.rejected.md`. diff --git a/memory/candidates.rejected.md b/memory/candidates.rejected.md new file mode 100644 index 0000000..7a34931 --- /dev/null +++ b/memory/candidates.rejected.md @@ -0,0 +1,4 @@ +# Rejected Candidates + +Claims that were staged in `memory/candidates.md` but rejected with a +`**Why rejected:**` rationale. Preserve entries here to prevent re-litigation. diff --git a/memory/semantic.md b/memory/semantic.md new file mode 100644 index 0000000..8292a3a --- /dev/null +++ b/memory/semantic.md @@ -0,0 +1,24 @@ +# Semantic Memory — agent-memory-kit + +## Core Systems + +- **Purpose:** agent-memory-kit is a vendored, markdown-first project memory kit for coding agents. It stores durable project context in repo-local markdown under git, with no daemon, database, MCP server, dashboard, or telemetry. +- **Generator:** `generate.py` reads `.agent/project.yaml` and renders agent entrypoints/configs through adapters in `adapters/`. It supports `init`, per-agent generation, `all`, `all --force`, and `all --check`. +- **Adapters:** Claude Code, Codex, Hermes, Cursor, Gemini CLI, Windsurf, OpenClaw, and Antigravity share the same memory files. Adapters expose `generate()`, `check()`, and `referenced_memory_files()`. +- **Managed sections:** Generated markdown entrypoints use `` / `` sentinels. Regeneration replaces only the managed block and preserves user content outside it. +- **Approval mode:** `memory.approval_mode` in `.agent/project.yaml` controls whether semantic/decision memory is direct-write (`auto`) or propose-first (`review`). `memory/working.md`, `dev/[task]/context.md`, and candidate files are always auto. +- **Stage/graduate memory:** `memory/candidates.md` stages recurring lessons; promotion to `memory/semantic.md` requires a `**Why accepted:**` rationale. Rejections move to `memory/candidates.rejected.md` with `**Why rejected:**`. +- **Self-check target:** The kit repo has its own `.agent/project.yaml` and generated `AGENTS.md` so CI can run `python3 generate.py all . --check` against real checked-in generated output. + +## Key Patterns + +- Keep the kit vendored and repo-local; do not introduce global installs or load-bearing state outside markdown. +- Prefer deterministic generated output plus `--check` drift detection over runtime services. +- Generated files must be reproducible from `generate.py`, `adapters/`, `templates/`, and `.agent/project.yaml`. +- If a generated file is manually corrected, update the source config/template/adapter so regeneration preserves the correction. + +## Active Areas + +- Add CI enforcement so generated-file drift blocks PR merge. +- Add a merge-closeout consistency protocol so memory, docs, generated files, hooks, and manuals are reconciled after merges. +- Later: add `generate.py doctor` as advisory automation for broader closeout checks.