memory-seed 1.2.0__py3-none-any.whl

memory_seed/__init__.py

@@ -0,0 +1,2 @@
+"""Memory Seed command line package."""
+

memory_seed/cli.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .core import doctor, get_version, init_project
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="memory-seed")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    init_parser = subparsers.add_parser("init", help="copy Memory Seed into this project")
+    init_parser.add_argument("--dry-run", action="store_true", help="show planned files without writing")
+    init_parser.add_argument("--force", action="store_true", help="backup and overwrite existing seed files")
+
+    subparsers.add_parser("doctor", help="check Memory Seed control-plane files")
+    subparsers.add_parser("version", help="print Memory Seed control-plane version")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "version":
+        print(get_version())
+        return 0
+
+    if args.command == "doctor":
+        result = doctor()
+        if result.ok:
+            print("Memory Seed control plane looks healthy.")
+            return 0
+        for missing in result.missing:
+            print(f"Missing: {missing}")
+        for mismatch in result.version_mismatches:
+            print(
+                "Version mismatch: "
+                f"{mismatch['file']} expected {mismatch['expected']} "
+                f"but found {mismatch['actual']}"
+            )
+        return 1
+
+    if args.command == "init":
+        try:
+            result = init_project(dry_run=args.dry_run, force=args.force)
+        except FileExistsError as exc:
+            print(str(exc), file=sys.stderr)
+            print("Use --force to backup and replace existing seed files.", file=sys.stderr)
+            return 1
+
+        if args.dry_run:
+            for planned in result.planned:
+                print(f"Would copy: {planned}")
+            print("No files changed.")
+            return 0
+
+        for created in result.created:
+            print(f"Copied: {created}")
+        for backup in result.backed_up:
+            print(f"Backed up: {backup}")
+        if result.backed_up:
+            print("Added .AGENTS/backups/ to .gitignore to reduce accidental backup leaks.")
+        print("Next: open AGENTS.md and follow bootstrap mode.")
+        return 0
+
+    parser.error(f"Unknown command: {args.command}")
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

memory_seed/core.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+
+PACKAGE_ROOT = Path(__file__).resolve().parent
+SEED_ROOT = PACKAGE_ROOT / "seed"
+VERSION = "1.2"
+BACKUP_IGNORE_ENTRY = ".AGENTS/backups/"
+
+
+@dataclass(frozen=True)
+class SeedFile:
+    source: Path
+    destination: str
+
+
+@dataclass
+class InitResult:
+    changed: bool
+    planned: list[str] = field(default_factory=list)
+    created: list[str] = field(default_factory=list)
+    backed_up: list[str] = field(default_factory=list)
+
+
+@dataclass
+class DoctorResult:
+    ok: bool
+    missing: list[str] = field(default_factory=list)
+    version_mismatches: list[dict[str, str]] = field(default_factory=list)
+
+
+SEED_FILES = [
+    SeedFile(SEED_ROOT / "AGENTS.md", "AGENTS.md"),
+    SeedFile(SEED_ROOT / "CLAUDE.md", "CLAUDE.md"),
+    SeedFile(SEED_ROOT / "GEMINI.md", "GEMINI.md"),
+    SeedFile(SEED_ROOT / ".AGENTS" / "agent-rules.md", ".AGENTS/agent-rules.md"),
+    SeedFile(
+        SEED_ROOT / ".AGENTS" / "project-bootstrap.md",
+        ".AGENTS/project-bootstrap.md",
+    ),
+]
+
+
+def get_version() -> str:
+    return VERSION
+
+
+def init_project(cwd: str | Path = ".", dry_run: bool = False, force: bool = False) -> InitResult:
+    target_root = Path(cwd).resolve()
+    planned = [seed_file.destination for seed_file in SEED_FILES]
+    existing = [
+        seed_file.destination
+        for seed_file in SEED_FILES
+        if (target_root / seed_file.destination).exists()
+    ]
+
+    if dry_run:
+        return InitResult(changed=False, planned=planned)
+
+    if existing and not force:
+        raise FileExistsError(
+            "Refusing to overwrite existing files: " + ", ".join(existing)
+        )
+
+    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    created: list[str] = []
+    backed_up: list[str] = []
+
+    for seed_file in SEED_FILES:
+        destination = target_root / seed_file.destination
+
+        if destination.exists() and force:
+            _ensure_backup_gitignore(target_root)
+            backup_relative = Path(".AGENTS") / "backups" / timestamp / seed_file.destination
+            backup_path = target_root / backup_relative
+            backup_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(destination, backup_path)
+            backed_up.append(backup_relative.as_posix())
+
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(seed_file.source, destination)
+        created.append(seed_file.destination)
+
+    return InitResult(
+        changed=True,
+        planned=planned,
+        created=created,
+        backed_up=backed_up,
+    )
+
+
+def doctor(cwd: str | Path = ".") -> DoctorResult:
+    target_root = Path(cwd).resolve()
+    missing: list[str] = []
+    version_mismatches: list[dict[str, str]] = []
+
+    for seed_file in SEED_FILES:
+        candidate = target_root / seed_file.destination
+        if not candidate.exists():
+            missing.append(seed_file.destination)
+            continue
+
+        actual = _read_memory_system_version(candidate)
+        if actual != VERSION:
+            version_mismatches.append(
+                {
+                    "file": seed_file.destination,
+                    "expected": VERSION,
+                    "actual": actual or "missing",
+                }
+            )
+
+    return DoctorResult(
+        ok=not missing and not version_mismatches,
+        missing=missing,
+        version_mismatches=version_mismatches,
+    )
+
+
+def _read_memory_system_version(path: Path) -> str | None:
+    match = re.search(
+        r"^memory-system-version:\s*([^\s]+)\s*$",
+        path.read_text(encoding="utf-8"),
+        re.MULTILINE,
+    )
+    if not match:
+        return None
+    return match.group(1)
+
+
+def _ensure_backup_gitignore(target_root: Path) -> None:
+    gitignore = target_root / ".gitignore"
+    if gitignore.exists():
+        content = gitignore.read_text(encoding="utf-8")
+    else:
+        content = ""
+
+    lines = content.splitlines()
+    if BACKUP_IGNORE_ENTRY in lines:
+        return
+
+    prefix = content
+    if prefix and not prefix.endswith(("\n", "\r\n")):
+        prefix += "\n"
+    gitignore.write_text(prefix + BACKUP_IGNORE_ENTRY + "\n", encoding="utf-8")

memory_seed/seed/.AGENTS/agent-rules.md

@@ -0,0 +1,214 @@
+---
+memory-system-version: 1.2
+tags:
+  - ai-memory
+  - agent-rules
+  - operating-mode
+---
+
+# Agent Rules
+
+These rules define how AI agents should use this project's local memory system.
+
+## Core Principle
+
+The `.AGENTS` folder is the source of operational memory for this repository. Keep it small, navigable, and local-first so an agent can quickly understand the project without loading historical noise by default.
+
+Memory Seed targets file-reading AI coding agents. Keep shared memory in plain Markdown, use predictable paths, keep read order explicit, and avoid vendor-specific assumptions in the memory core. Tool-specific routing files may exist, but they must point into the same `.AGENTS/` system.
+
+## Reusable Seed Files
+
+The reusable seed control plane is:
+
+```text
+AGENTS.md        # Generic agent entry point
+CLAUDE.md        # Claude Code routing file
+GEMINI.md        # Gemini CLI routing file
+.AGENTS/
+  agent-rules.md
+  project-bootstrap.md
+```
+
+Project-specific operating files are generated during bootstrap and are not version-archived with the seed:
+
+```text
+.AGENTS/
+  index.md
+  context.md
+  style.md
+  sessions/
+```
+
+## Active Memory Structure
+
+Required files and folders:
+
+```text
+.AGENTS/
+  agent-rules.md        # This workflow contract
+  index.md              # Top-level pointer and read order
+  context.md            # Authoritative project context, current state, durable facts
+  style.md              # Writing, naming, and formatting conventions
+  sessions/             # Append-only dated session logs
+```
+
+`project-bootstrap.md` may exist but is not part of the operating-mode read order.
+
+## Start-of-Work Routine
+
+At the start of a session:
+
+1. Read `.AGENTS/agent-rules.md`.
+2. Read `.AGENTS/index.md`.
+3. Read `.AGENTS/context.md`, especially `Fast Orientation` and `Current State`.
+4. Read `.AGENTS/style.md` when writing or editing project documentation.
+5. Read recent `.AGENTS/sessions/*` only when historical detail is needed.
+
+If the repository root is unclear, identify it first and note any uncertainty in `context.md` only if it is durable project context.
+
+
+## File Change Permission Model
+
+Agents must treat `.AGENTS` and agent-routing files according to these buckets.
+
+### Locked Unless Explicitly Requested
+
+These files define the reusable control plane for agents. Do not modify them unless the user explicitly asks for agent workflow, bootstrap, routing, or memory-structure changes.
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `GEMINI.md`
+- `.AGENTS/agent-rules.md`
+- `.AGENTS/project-bootstrap.md`
+
+Also locked unless explicitly requested:
+
+- Adding new top-level `.AGENTS` files.
+- Deleting existing `.AGENTS` files.
+- Renaming `.AGENTS` files or folders.
+- Reorganizing the `.AGENTS` structure.
+- Recreating obsolete files such as `current.md`, `project-memory.md`, or `memory.md`.
+- Editing prior session logs except for explicit repair, archival cleanup, or user-requested correction.
+
+### End-Of-Session Restricted Updates
+
+These files should normally be updated only during the end-of-session routine, after the agent has enough context to distinguish durable facts from temporary work.
+
+- `.AGENTS/context.md`: Update when durable/current project facts changed, including project structure, current priorities, artifact paths, stable decisions, operational risks, or project type/risk classification.
+- `.AGENTS/index.md`: Update only when read order, hot facts, active workflow, or key project pointers changed.
+- `.AGENTS/style.md`: Update only when durable conventions, project type/risk implications, security posture, coding standards, documentation standards, or workflow conventions changed.
+
+Do not edit these files for ordinary implementation details, temporary observations, or raw session history. Put that detail in `.AGENTS/sessions/YYYY-MM-DD.md`.
+
+Immediate-update exception: update `.AGENTS/context.md`, `.AGENTS/index.md`, or `.AGENTS/style.md` during a session only when leaving the current content stale would immediately mislead the active work, route an agent to the wrong files, preserve an unsafe assumption, or cause repeated incorrect actions.
+
+For restricted files, the agent must be able to explain why the file's ownership scope was affected.
+
+### Routine Append
+
+- `.AGENTS/sessions/YYYY-MM-DD.md`: Append concise notes for meaningful work completed on that date. Do not log trivial edits, routine command output, or temporary observations unless they affect future handoff, risk, or decisions.
+
+Session logs are append-only. Today's file may be appended during normal work or at the end of the session. Prior dated session files must not be edited unless the user explicitly asks for repair, archival cleanup, or correction.
+
+## End-of-Work Routine
+
+At the end of meaningful work:
+
+1. Append a concise note to `.AGENTS/sessions/YYYY-MM-DD.md`.
+2. Review whether `.AGENTS/context.md` needs consolidation because project structure, current priorities, workflow logic, artifacts, durable decisions, or operational risks changed.
+3. Update `.AGENTS/index.md` only when read order, hot facts, active workflow, or key project pointers changed.
+4. Update `.AGENTS/style.md` only when durable conventions, project type/risk implications, security posture, coding standards, documentation standards, or workflow conventions changed.
+
+Session logs are append-only. Do not rewrite or compress old session entries unless the user explicitly asks for archival cleanup.
+
+## Context Ownership
+
+`context.md` owns:
+
+- Project purpose and business goal.
+- Fast orientation for new agents.
+- Current state, active priorities, and immediate risks.
+- Repository traversal guidance and important folders/files.
+- Stable model, routing, production, and artifact decisions.
+- Memory workflow rules that affect future agents.
+
+`index.md` owns:
+
+- Minimal read order.
+- Short pointers to the files that matter.
+- Current hot facts that prevent loading the wrong notebook or stale artifact path.
+
+`sessions/*` owns:
+
+- Chronological work logs.
+- Experiments, failed attempts, temporary observations, and detailed implementation notes.
+- Evidence that may later be promoted into `context.md`.
+
+## Consolidation Routine
+
+Periodically review recent session logs and promote only stable, reusable facts into `context.md`. Keep `context.md` concise enough for fast agent orientation, but complete enough to traverse the repository and understand why the project is structured as it is.
+
+Examples of facts worth promoting:
+
+- Notebook ownership changes.
+- Stable artifact paths.
+- Workflow objective changes.
+- Production runtime assumptions.
+- Current evaluation criteria.
+- Known stale outputs or rerun requirements.
+
+Examples that should usually stay in sessions only:
+
+- One-off debugging traces.
+- Temporary hypotheses.
+- Intermediate command outputs.
+- Superseded experiments.
+
+## Memory Doctor Checklist
+
+A clean `.AGENTS` folder should satisfy all of the following:
+
+- `AGENTS.md` exists and routes initialized projects to operating mode.
+- `.AGENTS/project-bootstrap.md` exists, is marked bootstrap-only, and is not required in the operating-mode read order.
+- `.AGENTS/index.md` points to the active files only.
+- `.AGENTS/context.md` contains `Fast Orientation`, `Current State`, and `Project Type And Risk`.
+- `.AGENTS/sessions/` contains dated append-only logs.
+- `.AGENTS/agent-rules.md` describes operating-mode files without requiring bootstrap guidance.
+- The file change permission buckets are present and distinguish locked, restricted, and routine append files.
+- End-of-session restricted files are consolidated deliberately, not edited for temporary observations.
+- Important workflow/output/artifact changes are represented in `context.md`, not only in a session log.
+
+## Session Log Format
+
+Use dated files under `.AGENTS/sessions/` with short entries such as:
+
+```markdown
+## 2026-05-02 - Project setup and workflow update
+
+- Updated the project workflow or implementation area touched today.
+- Recorded the key decision, artifact, or file path that future agents need.
+- Follow-up: note any rerun, validation, review, or unresolved risk.
+```
+
+Prefer concise bullets. Capture meaningful decisions, durable changes, follow-up risk, or handoff context. Do not log trivial work or every command.
+
+## Public Memory Hygiene
+
+Treat `.AGENTS` files as potentially publishable unless the user explicitly says the repository will always remain private. Do not write secrets, credentials, tokens, private keys, sensitive account details, client confidential information, or unnecessary personal data into `context.md`, `style.md`, `index.md`, or session logs.
+
+When a project may become public, keep session entries focused on durable technical decisions and omit private local paths, private identities, and sensitive operational details unless the user explicitly asks to preserve them.
+
+## Bootstrap Boundary
+
+This repository is in operating mode because `.AGENTS/index.md`, `.AGENTS/context.md`, `.AGENTS/style.md`, and `.AGENTS/sessions/` exist.
+
+Do not read or apply `.AGENTS/project-bootstrap.md` during operating mode. That file is only for brand-new projects or incomplete `.AGENTS` folders where `.AGENTS/` is void except for `agent-rules.md` and `project-bootstrap.md`.
+
+If a user explicitly asks to bootstrap a new project, use `.AGENTS/project-bootstrap.md` as the bootstrap procedure for that new project. Do not apply bootstrap rules to this initialized project unless the user explicitly asks to rebuild the memory system.
+
+
+
+
+
+
+

memory_seed/seed/.AGENTS/project-bootstrap.md

@@ -0,0 +1,308 @@
+---
+memory-system-version: 1.2
+tags:
+  - ai-memory
+  - project-bootstrap
+---
+
+# Project Bootstrap Guide
+
+This file is only for initializing a brand-new project or repairing an incomplete `.AGENTS` folder.
+
+Do not read or apply this file during normal operating mode. If `.AGENTS/index.md`, `.AGENTS/context.md`, `.AGENTS/style.md`, and `.AGENTS/sessions/` already exist, use `.AGENTS/agent-rules.md` and `.AGENTS/index.md` instead.
+
+## When This File Applies
+
+Use this file only when the project is empty or the target project is still at the reusable seed state:
+
+```text
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+.AGENTS/
+  agent-rules.md
+  project-bootstrap.md
+```
+
+Once `.AGENTS/index.md`, `.AGENTS/context.md`, `.AGENTS/style.md`, and `.AGENTS/sessions/` exist, bootstrap mode is complete.
+
+## Template Hygiene
+
+- YAML tags in newly created files must be generated from the new project name, project type, and file role. Do not copy source-project tags such as a previous repository name.
+- `context.md` and `style.md` must not inherit source-project facts, paths, model names, stack assumptions, risks, or workflow details from the project where this bootstrap guide was copied from.
+- Reuse the memory structure and process, not the source project's domain content.
+- Keep the memory core usable by file-reading AI coding agents: plain Markdown, predictable paths, explicit read order, and minimal vendor-specific assumptions.
+- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.AGENTS/agent-rules.md`, and `.AGENTS/project-bootstrap.md` are reusable control-plane files. Copy the standard baseline for these files unless the user explicitly requests a different memory workflow.
+- Tool-specific routing files should route into `AGENTS.md` and the shared `.AGENTS/` memory core rather than creating separate vendor memories.
+- Keep the same operating/bootstrap boundary across projects so initialized projects do not drift into incompatible agent-routing structures.
+- Treat generated memory files as potentially publishable unless the user explicitly says the target repository will remain private. Never seed secrets, credentials, tokens, private keys, sensitive account details, client confidential information, or unnecessary personal data into generated memory.
+
+
+## Version Policy
+
+`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.AGENTS/agent-rules.md`, and `.AGENTS/project-bootstrap.md` must share the same `memory-system-version` value because they define the reusable control plane together.
+
+When the standard baseline changes:
+
+- Update the shared `memory-system-version` only when the control-plane behaviour changes materially.
+- Keep all reusable control-plane files aligned to the same version.
+- Before replacing reusable control-plane files, archive the previous versions under `.AGENTS/archive/<version>/`.
+- Record the change in `.AGENTS/sessions/YYYY-MM-DD.md` for the project where the change is made.
+- Do not change the version for project-specific `context.md`, `index.md`, or `style.md` updates.
+
+## Bootstrap Goal
+
+Create a minimal, project-specific memory system that lets future agents understand:
+
+- what the project is
+- why it exists
+- how to navigate it
+- what conventions to follow
+- what risks matter
+- where chronological work history is recorded
+
+## Step 1: Inspect Local Evidence
+
+Before asking questions, inspect available project evidence:
+
+- folder and file names
+- README or notes
+- dependency files
+- notebooks
+- source folders
+- docs folders
+- deployment files
+- data folders
+- existing conventions
+
+If the folder is empty or ambiguous, ask targeted bootstrap questions.
+
+## Step 2: Ask Bootstrap Questions
+
+Ask no more than five questions. Ask only questions that materially change `context.md` or `style.md`.
+
+Recommended questions:
+
+1. What type of project is this: data science/ML, production app/API, website, library/package, writing/diary/second brain, research notes, automation script, or something else?
+2. Is this intended for production, public release, internal use, private/local use only, or exploratory work?
+3. Does it handle sensitive data, user data, credentials, payments, personal notes, or proprietary business data?
+4. What outputs matter most: code quality, reproducible analysis, polished writing, visualisation, deployment reliability, fast iteration, or knowledge capture?
+5. Will this project be synced, published, deployed, shared, or connected to external services?
+
+If the user already gave enough information, proceed without asking.
+
+## Step 3: Classify The Project
+
+Record these fields in `.AGENTS/context.md`:
+
+- Project type.
+- Intended use.
+- Primary audience.
+- Risk level: private/local, internal, public, production, or regulated/sensitive.
+- Security posture.
+- Primary outputs.
+- Expected workflow.
+
+Use a cautious security posture when risk is unclear and the project may include secrets, credentials, personal data, user data, payments, proprietary data, network exposure, or destructive automation.
+
+If the project may be public, record privacy constraints in `.AGENTS/context.md` and keep `.AGENTS/sessions/` entries free of sensitive details.
+
+## Step 4: Create The Files
+
+Create or update every required bootstrap output. Bootstrap is incomplete until all of these exist:
+
+```text
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+.AGENTS/
+  agent-rules.md
+  project-bootstrap.md
+  index.md
+  context.md
+  style.md
+  sessions/
+    YYYY-MM-DD.md
+```
+
+Create root `AGENTS.md` as the entry point for future agents if it does not already exist.
+Create root `CLAUDE.md` as the Claude Code routing file if it does not already exist.
+Create root `GEMINI.md` as the Gemini CLI routing file if it does not already exist.
+
+`AGENTS.md` should say:
+
+- In operating mode, read `.AGENTS/agent-rules.md`, `.AGENTS/index.md`, and `.AGENTS/context.md`.
+- Do not read or apply `.AGENTS/project-bootstrap.md` once `.AGENTS/index.md`, `.AGENTS/context.md`, `.AGENTS/style.md`, and `.AGENTS/sessions/` exist.
+- Use `.AGENTS/project-bootstrap.md` only when `.AGENTS/` is void except for `agent-rules.md` and `project-bootstrap.md`.
+
+`CLAUDE.md` should say:
+
+- The canonical agent instructions for the repository are in `AGENTS.md`.
+- Claude Code should open `AGENTS.md` before planning, editing, reviewing, or running commands.
+- Tool-specific behavior may adapt tooling, but not policy.
+- `CLAUDE.md` is a routing file, not a replacement memory system.
+
+`GEMINI.md` should say:
+
+- The canonical agent instructions for the repository are in `AGENTS.md`.
+- Gemini CLI should open `AGENTS.md` before planning, editing, reviewing, or running commands.
+- Tool-specific behavior may adapt tooling, but not policy.
+- `GEMINI.md` is a routing file, not a replacement memory system.
+
+## Step 5: Seed context.md
+
+Minimum sections:
+
+```markdown
+# Project Context
+
+## Purpose
+## Fast Orientation
+## Current State
+## Project Type And Risk
+## Agent Start Here
+## Project Folder Structure
+## Core Workflow
+## Key Outputs
+## Security And Privacy Notes
+## Memory Rules
+```
+
+`context.md` must be enough for an agent to traverse the project without guessing.
+
+## Step 6: Seed index.md
+
+Keep `index.md` short:
+
+```markdown
+# Agent Memory Index
+
+## Always Read
+
+- `.AGENTS/agent-rules.md`
+- `.AGENTS/context.md`
+- `.AGENTS/style.md` when editing code, docs, or project conventions
+
+## Historical Memory
+
+- `.AGENTS/sessions/*.md`
+
+## Hot Facts
+
+- Project type:
+- Current priority:
+- Main output:
+- Current risk:
+
+## Bootstrap Boundary
+
+Do not read or apply `.AGENTS/project-bootstrap.md` during operating mode.
+```
+
+## Step 7: Select Style Profile And Generate style.md
+
+Do not copy a generic style guide. Bootstrap owns the style decision because `style.md` does not exist yet in a brand-new target project. Generate `style.md` from the classified project type, intended use, audience, outputs, workflow, and risk.
+
+Include a short classification block:
+
+```markdown
+## Style Basis
+
+- Project type:
+- Intended use:
+- Risk level:
+- Why these conventions apply:
+```
+
+Select one primary style profile, then add any secondary profile needed for risk or workflow. Record the selected profile in both `context.md` and `style.md`.
+
+Style profiles:
+
+- Memory-system development: use when the target project develops, tests, or distributes the memory seed itself. Emphasize control-plane vs generated-file boundaries, version policy, archive rules, portability, and session-log rationale.
+- Software or production project: use for apps, APIs, websites, packages, libraries, and tools. Emphasize architecture, setup commands, test commands, dependency hygiene, secure defaults, logging without sensitive data, deployment assumptions, and rollback-aware changes.
+- Data science or ML: use for notebooks, experiments, model training, analysis, and data pipelines. Emphasize reproducibility, data leakage prevention, train/validation/test boundaries, experiment tracking, notebook execution order, artifact versioning, and metric discipline.
+- Writing, essay, or research: use for drafts, long-form writing, source synthesis, and argument development. Emphasize source traceability, audience, thesis, outline, citation expectations, assumptions, methodology, and separation of evidence from interpretation.
+- Second-brain or ideation: use for personal knowledge bases, diary-like workspaces, idea development, and exploratory notes. Emphasize low-friction capture, privacy, durable naming, linking conventions, uncertainty, and sync/backup awareness.
+- Automation or scripting: use for local utilities, initialization scripts, data movement, and repeatable operational tasks. Emphasize idempotency, dry-run behavior where useful, explicit paths, logging, safe failure modes, and protection against destructive commands.
+- Sensitive or private project: add as a secondary profile when the target may contain personal data, user data, credentials, payments, proprietary material, client data, health data, financial data, or other sensitive information. Emphasize minimization, redaction, secrets handling, and explicit export/sync/publication risks.
+
+Minimum generated `style.md` structure:
+
+```markdown
+# Project Style Guide
+
+## Style Basis
+
+- Project type:
+- Primary style profile:
+- Secondary style profile:
+- Intended use:
+- Primary audience:
+- Risk level:
+- Why these conventions apply:
+
+## Global Conventions
+
+## Project-Specific Conventions
+
+## Security And Privacy Conventions
+
+## File-Specific Guidance
+
+### `index.md`
+
+### `context.md`
+
+### `style.md`
+
+### `sessions/YYYY-MM-DD.md`
+```
+
+Profile-specific guidance:
+
+- Data science or ML: reproducibility, data leakage prevention, train/validation/test boundaries, experiment tracking, notebook execution order, artifact versioning, metric discipline.
+- Production app, API, website, or SaaS: secure defaults, input validation, authentication/authorization expectations, secrets handling, dependency hygiene, logging without sensitive data, tests, deployment checks, rollback-aware changes.
+- Library or package: API stability, semantic versioning, typing, tests, public documentation, compatibility policy, changelog expectations.
+- Writing, diary, notes, or second brain: clarity, linking conventions, metadata/tagging, privacy expectations, durable naming, low-friction capture, sync/backup awareness.
+- Automation or scripting: idempotency, dry-run behaviour where useful, explicit paths, logging, safe failure modes, protection against destructive commands.
+- Research project: source traceability, assumptions, methodology notes, reproducibility, separation of evidence from interpretation.
+
+Security must be proportional:
+
+- Production-facing, public, networked, or user-data projects require explicit security best practices.
+- Private local knowledge projects require privacy and backup guidance, not unnecessary production process.
+- If uncertain, protect secrets, credentials, personal data, and destructive operations by default.
+
+## Step 8: Create First Session Log
+
+Create `.AGENTS/sessions/YYYY-MM-DD.md` and record:
+
+- bootstrap date
+- project classification
+- questions asked and answers received
+- files created
+- assumptions
+- follow-up gaps
+
+Keep sessions append-only.
+
+## Step 9: Validate Bootstrap
+
+Bootstrap is incomplete until all checks pass:
+
+- `AGENTS.md` exists.
+- `CLAUDE.md` exists and routes Claude Code to `AGENTS.md`.
+- `GEMINI.md` exists and routes Gemini CLI to `AGENTS.md`.
+- `.AGENTS/agent-rules.md` exists and defines operating-mode memory rules.
+- `.AGENTS/project-bootstrap.md` exists and is marked bootstrap-only.
+- `.AGENTS/index.md` exists, is concise, and points only to active files.
+- `.AGENTS/context.md` exists and includes project type, risk, purpose, current state, traversal guidance, and memory rules.
+- `.AGENTS/style.md` exists and matches the project type, intended use, and risk level.
+- `.AGENTS/sessions/YYYY-MM-DD.md` exists and records bootstrap decisions.
+- No required bootstrap output is missing.
+- No stale file references point agents to obsolete memory files.
+- Security posture matches risk level.
+- `context.md` is enough for repo traversal without guessing.
+- No active operating-mode file requires agents to read bootstrap guidance after initialization.
+
+After validation, switch to operating mode and stop using this file.

memory_seed/seed/AGENTS.md

@@ -0,0 +1,39 @@
+---
+memory-system-version: 1.2
+tags:
+  - agent-entry
+  - ai-memory
+---
+
+# Agent Entry Point
+
+This repository uses `.AGENTS/` as its agent memory and onboarding system.
+
+Memory Seed is designed for file-reading AI coding agents. Keep the shared memory core in plain Markdown with predictable paths, explicit read order, and minimal vendor-specific assumptions. Tool-specific routing files should point into the same `.AGENTS/` memory core.
+
+## Operating Mode
+
+This repository is already initialized. Start here:
+
+1. Read `.AGENTS/agent-rules.md`.
+2. Read `.AGENTS/index.md` for the compact memory index.
+3. Read `.AGENTS/context.md` for project orientation and current state.
+4. Follow the start-of-work and end-of-work routines in `.AGENTS/agent-rules.md`.
+
+Do not read or apply `.AGENTS/project-bootstrap.md` during operating mode.
+
+## Bootstrap Mode
+
+Use `.AGENTS/project-bootstrap.md` only when initializing a brand-new project or repairing a missing/incomplete `.AGENTS` memory system. The normal bootstrap seed state is:
+
+```text
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+.AGENTS/
+  agent-rules.md
+  project-bootstrap.md
+```
+
+If `.AGENTS/` is missing, partial, or corrupted, use `.AGENTS/project-bootstrap.md` only long enough to restore the standard structure. Once `.AGENTS/index.md`, `.AGENTS/context.md`, `.AGENTS/style.md`, and `.AGENTS/sessions/` exist, bootstrap mode is complete and future agents must use operating mode.
+

memory_seed/seed/CLAUDE.md

@@ -0,0 +1,18 @@
+---
+memory-system-version: 1.2
+tags:
+  - agent-entry
+  - ai-memory
+---
+
+# Claude Instructions
+
+The canonical agent instructions for this repository are in `AGENTS.md`.
+
+Before planning, editing, reviewing, or running commands:
+1. Open `AGENTS.md`.
+2. Follow its instructions.
+3. If tool-specific behavior is needed, adapt only the tooling, not the policy.
+
+Do not treat this file as a replacement for `AGENTS.md`.
+

memory_seed/seed/GEMINI.md

@@ -0,0 +1,17 @@
+---
+memory-system-version: 1.2
+tags:
+  - agent-entry
+  - ai-memory
+---
+
+# Gemini Instructions
+
+The canonical agent instructions for this repository are in `AGENTS.md`.
+
+Before planning, editing, reviewing, or running commands:
+1. Open `AGENTS.md`.
+2. Follow its instructions.
+3. If tool-specific behavior is needed, adapt only the tooling, not the policy.
+
+Do not treat this file as a replacement for `AGENTS.md`.

memory_seed-1.2.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: memory-seed
+Version: 1.2.0
+Summary: Portable local memory seed for file-reading AI coding agents
+Author: John Tshibuyi
+License: MIT
+Keywords: ai,agents,memory,markdown,local-first
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Memory Seed
+
+Memory Seed is a portable local memory system for AI coding agents.
+
+It provides a small set of plain Markdown control-plane files that can be planted into a new or existing project. During bootstrap, the seed generates project-specific operating memory so future agent sessions can recover the project's purpose, current state, conventions, risks, and recent decisions without depending on vendor-hosted memory.
+
+## Goals
+
+- Keep project memory local, inspectable, and portable.
+- Support file-reading AI coding agents through predictable Markdown files.
+- Route tool-specific entry files into one shared `.AGENTS/` memory core.
+- Generate project-specific `index.md`, `context.md`, `style.md`, and session logs during bootstrap.
+- Archive reusable control-plane versions while keeping generated project memory outside version archives.
+
+## Reusable Seed Files
+
+```text
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+.AGENTS/
+  agent-rules.md
+  project-bootstrap.md
+```
+
+## Generated Per-Project Files
+
+```text
+.AGENTS/
+  index.md
+  context.md
+  style.md
+  sessions/
+```
+
+## Current Version
+
+The current reusable control-plane version is `1.2`.
+
+Archived reusable versions are stored under `.AGENTS/archive/<version>/`.
+
+## Python CLI
+
+Memory Seed includes a small Python CLI.
+
+From this repository, run:
+
+```powershell
+python -m memory_seed.cli version
+python -m memory_seed.cli doctor
+python -m memory_seed.cli init --dry-run
+```
+
+The `init` command copies only the reusable seed files into the current folder:
+
+```text
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+.AGENTS/agent-rules.md
+.AGENTS/project-bootstrap.md
+```
+
+It does not copy generated project memory such as `.AGENTS/context.md`, `.AGENTS/index.md`, `.AGENTS/style.md`, `.AGENTS/sessions/`, or `.AGENTS/archive/`.
+
+Use `--dry-run` to preview without changing files. Use `--force` only when you intentionally want to back up and replace existing seed files.
+
+When `--force` creates backups, Memory Seed adds `.AGENTS/backups/` to the target project's `.gitignore` to reduce the chance of committing replaced local memory files.
+
+## Public Memory Hygiene
+
+Memory Seed files are plain Markdown and may be committed with a project. Treat `.AGENTS` files as publishable unless the project is explicitly private.
+
+Do not put secrets, credentials, tokens, private keys, sensitive account details, client confidential information, or unnecessary personal data into generated memory files or session logs.
+
+## Publishing
+
+This repository is configured for PyPI trusted publishing from GitHub Actions.
+
+PyPI pending publisher settings should match:
+
+```text
+PyPI Project Name: memory-seed
+Owner: jnl-tshi
+Repository name: memory-seed
+Workflow name: publish.yml
+Environment name: pypi
+```
+
+The publish workflow lives at `.github/workflows/publish.yml`. It runs tests, builds the package with `uv build`, and publishes through PyPI's trusted publisher flow.

memory_seed-1.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+memory_seed/__init__.py,sha256=33tZjEWwLYbrGTB0iDaWjLX6o0lP1oIdZBzzq7fVoa8,41
+memory_seed/cli.py,sha256=YmYzrBPUd_xh3tLHVZ0-SCTzgmDTQPSfAJpKC6DdYCI,2375
+memory_seed/core.py,sha256=upKavoPT-FLsRD7I3wp91xs-RuaWSNUJMA8_A2d9mB8,4264
+memory_seed/seed/AGENTS.md,sha256=gVXEViOUeCVmPBSWpEAKREbAKfhVv0MRYKW5bHXpHkI,1427
+memory_seed/seed/CLAUDE.md,sha256=9WNp_VzvRjzxttZRutn3oH372Fqk1KKYw0aUQdmyFeY,418
+memory_seed/seed/GEMINI.md,sha256=AdP49o_XxlYZ-as5y-j0kOi58lFb4Omx-YF-cBKQEqE,414
+memory_seed/seed/.AGENTS/agent-rules.md,sha256=z5JmEseYbx_Vsq9zbkCqxByU6NbXsVLjIZE-y_6daSM,9509
+memory_seed/seed/.AGENTS/project-bootstrap.md,sha256=SfvkY1FVFBdGYvifEQ8NoeBBXpNso79IJGAVJ-kfxso,13251
+memory_seed-1.2.0.dist-info/licenses/LICENSE,sha256=CFS2jTaG9ypciMpWU4prLOUsKnZUdPUPqm31bjztVU0,1071
+memory_seed-1.2.0.dist-info/METADATA,sha256=jvdSKiEwDrhedWfZVDvTq7bLqqrIHi8c57l_Ln844k8,3559
+memory_seed-1.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+memory_seed-1.2.0.dist-info/entry_points.txt,sha256=PyB34Pa83GHeOBFm7DWdyD2gGg1aPzn5WExpfWVmjjs,53
+memory_seed-1.2.0.dist-info/top_level.txt,sha256=wF5uUiIt-AHlYvJWG8hzwUv47OMMUVaS7JZB5kBszDo,12
+memory_seed-1.2.0.dist-info/RECORD,,

memory_seed-1.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

memory_seed-1.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+memory-seed = memory_seed.cli:main

memory_seed-1.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 John Tshibuyi
+
+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.
+

memory_seed-1.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+memory_seed