memento-lifecycle 0.1.0__tar.gz

memento_lifecycle-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,67 @@
+name: Publish Python package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify-build:
+    name: Verify and build package
+    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.11"
+          cache: pip
+
+      - name: Install package and release tooling
+        run: python -m pip install --upgrade -e '.[dev,release]'
+
+      - name: Run tests and static checks
+        run: |
+          python -m pytest -q
+          python -m ruff check .
+          python -m compileall -q src tests
+          memento doctor --json
+          memento sample-smoke --workspace /tmp/memento-release-smoke --json
+
+      - name: Build source and wheel distributions
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: twine check dist/*
+
+      - name: Upload distribution artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: verify-build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download distribution artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

memento_lifecycle-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+
+# Node/tooling
+node_modules/
+
+# Local Hermes/Ouroboros runtime state
+.hermes/runtime/
+.memento/
+.ouroboros/data/
+.ouroboros/runs/
+
+# Secrets
+.env
+*.secret
+secrets/

memento_lifecycle-0.1.0/.ouroboros/seeds/README.yaml

@@ -0,0 +1,19 @@
+metadata:
+  name: memento-seed-roadmap-index
+  created_at: '2026-05-12T13:59:28Z'
+  origin: hermes-assisted-ouroboros-fallback
+seeds:
+- phase: MVP
+  path: .ouroboros/seeds/memento-mvp.seed.yaml
+  summary: 'Foundation: externalized sessions, task graph, evidence, verification, dry-run routing, Graphify/agentmemory
+    hooks.'
+- phase: v1
+  path: .ouroboros/seeds/memento-v1.seed.yaml
+  summary: Real Codex/Aider adapters, worktree isolation, post-dispatch Graphify, memory/graph-aware routing.
+- phase: v2
+  path: .ouroboros/seeds/memento-v2.seed.yaml
+  summary: Goose/SWE-agent, confidence learning, verification enrichment, graph task proposals, repair/fallback
+    budgets.
+- phase: v3
+  path: .ouroboros/seeds/memento-v3.seed.yaml
+  summary: API worker pool/OpenHands, multi-executor competition, CI/team/release gates, graph-diff regression detection.

memento_lifecycle-0.1.0/.ouroboros/seeds/memento-mvp.seed.yaml

@@ -0,0 +1,162 @@
+metadata:
+  name: memento-mvp
+  version: 0.1.0
+  created_at: '2026-05-12T13:59:28Z'
+  origin: hermes-assisted-ouroboros-fallback
+  phase: MVP
+  ambiguity_score: 0.12
+  project: memento
+goal: 'Implement the Memento MVP foundation: durable externalized-state sessions, dependency-aware task graph basics,
+  evidence ledger basics, verification policy basics, explicit agentmemory hooks, Graphify checkpoint commands,
+  and explainable dry-run executor routing without relying on executor-native session memory.'
+constraints:
+- Keep Memento as the lifecycle source of truth for runs, sessions, plans, tasks, dispatches, evidence, and verification
+  decisions.
+- Do not depend on executor-native private sessions for correctness, retry, recovery, or progress reporting.
+- Executor summaries, reasoning traces, and self-assessments are advisory and cannot independently satisfy task
+  acceptance.
+- Preserve safety gates for destructive git operations, credentials, production/release actions, and forbidden paths.
+- Apply secret redaction and forbidden-path policies before storing evidence payloads, command output, diffs, or
+  artifacts.
+- Graphify must be checkpoint-driven by default; continuous watch is optional and must not be required for correctness.
+- agentmemory writeback must store only durable reusable lessons, not temporary task progress, raw logs, commit
+  hashes, PR numbers, or raw graph payloads.
+- 'MVP executor adapters should be safe by default: hermes-direct may execute local verification; Codex/Aider adapters
+  may be dry-run command construction unless explicitly enabled.'
+- Prefer minimal schema extensions that are compatible with the existing SQLite-backed local state model.
+- Do not introduce always-on background daemons or cron/watchdog behavior.
+- MVP should remain locally verifiable without requiring Codex, Aider, Goose, SWE-agent, OpenHands, or live Graphify
+  semantic extraction to succeed.
+scope:
+  in:
+  - Run/session/task/dispatch/evidence models for externalized-state orchestration.
+  - Canonical context bundle generation for ready tasks.
+  - Basic evidence ledger with trust levels and append-only semantics.
+  - Basic verification policy model and task accepted/rejected verdict evidence.
+  - Executor registry and route-task preview with hermes-direct plus dry-run Codex/Aider adapters.
+  - Graphify doctor/status/update checkpoint commands and graph evidence records.
+  - Explicit agentmemory prefetch/writeback hooks with strict filtering policy.
+  - CLI/report updates and tests for all MVP behavior.
+  out:
+  - Real Codex/Aider process invocation by default.
+  - Goose, SWE-agent, OpenHands, or OpenCode production adapters.
+  - Confidence-weighted executor performance memory.
+  - Automatic graph-derived task decomposition.
+  - Multi-executor competition or worker pools.
+acceptance_criteria:
+- name: Externalized session state
+  description: Memento stores durable run/session/task/dispatch/evidence state sufficient to reconstruct orchestration
+    after process restart.
+  verification: Create a run, plan, task, dispatch, and evidence record; restart the CLI process; verify status/report
+    reconstructs the same state from SQLite.
+- name: Task graph MVP
+  description: Approved plans can materialize a dependency-aware task graph with task status, dependencies, acceptance
+    criteria, verification policy, context refs, dispatch refs, and evidence refs.
+  verification: Unit tests create a task DAG, reject cycles, and mark tasks ready only after dependencies are accepted.
+- name: Canonical context bundle
+  description: Every ready task can produce an immutable executor-agnostic context bundle containing goal, plan
+    summary, task spec, dependencies, constraints, verification policy, repo refs, optional memory summary, optional
+    graph context, and output contract.
+  verification: CLI command or service method writes a bundle artifact; tests validate required fields and immutability
+    via stable bundle ID/hash.
+- name: Evidence ledger MVP
+  description: Memento records diffs, command results, test results, artifacts, graph snapshots/updates, routing
+    decisions, approvals, blocker reports, and QA verdicts with type, trust level, source, status, relationships,
+    and content refs.
+  verification: Tests append evidence, supersede evidence with a new record, and verify the prior record is not
+    silently mutated.
+- name: Verification policy MVP
+  description: Dispatch-ready tasks have a verification policy with required evidence and commands; accepted/rejected
+    transitions are computed from non-superseded evidence and the final verdict is recorded as evidence.
+  verification: A sample task with passing command evidence becomes accepted; a missing or failing required command
+    produces an actionable rejected verdict.
+- name: Explainable route-task preview
+  description: Memento can preview routing decisions with selected executor, rejected candidates, reasons, risk
+    adjustments, fallback chain, approval requirement, and context profile.
+  verification: CLI `memento route-task --task-id ... --json` returns a deterministic JSON decision without invoking
+    external executors.
+- name: Dry-run executor registry
+  description: Executor registry contains hermes-direct plus dry-run Codex and Aider entries with capabilities,
+    limitations, health status, and command construction that does not execute by default.
+  verification: Tests confirm dry-run dispatch builds invocation metadata and leaves executor_invoked=false unless
+    explicit invoke mode is configured.
+- name: Graphify doctor/status/update checkpoint
+  description: Memento doctor/status reports Graphify availability and graph state; graph update/checkpoint commands
+    record graph_update or graph_snapshot evidence and do not require continuous watch.
+  verification: With Graphify absent or failing, doctor reports optional unavailable; with a mocked graphify runner,
+    graph update records evidence and graph state.
+- name: agentmemory explicit hooks
+  description: Memento exposes explicit memory prefetch/writeback hooks that can attach compact memory summaries
+    to bundles and save only filtered durable lessons.
+  verification: Tests use a fake memory adapter to verify temporary task progress/raw logs are rejected while repo
+    convention lessons are accepted.
+- name: Local verification suite
+  description: MVP changes are covered by unit tests, ruff, compileall, doctor, and sample-smoke.
+  verification: Run `python -m pytest -q`, `python -m ruff check .`, `python -m compileall -q src tests`, `python
+    -m memento.cli doctor --json`, and `python -m memento.cli sample-smoke --workspace /tmp/memento-mvp-smoke --json`
+    successfully.
+ontology_schema:
+  name: MementoMVPFoundation
+  entities:
+  - name: MementoSession
+    fields:
+    - id
+    - run_id
+    - state
+    - goal
+    - plan_id
+    - task_graph_ref
+    - evidence_refs
+  - name: TaskNode
+    fields:
+    - id
+    - parent_id
+    - status
+    - freshness
+    - dependencies
+    - acceptance_criteria
+    - verification_policy
+    - evidence_refs
+  - name: EvidenceRecord
+    fields:
+    - id
+    - type
+    - trust_level
+    - status
+    - source
+    - content_ref
+    - relationships
+  - name: ContextBundle
+    fields:
+    - id
+    - task_id
+    - bundle_hash
+    - plan_summary
+    - constraints
+    - verification_policy
+    - output_contract
+  - name: RoutingDecision
+    fields:
+    - id
+    - task_id
+    - selected_executor
+    - rejected_executors
+    - reasons
+    - fallback_chain
+    - risk_adjustments
+evaluation_principles:
+- name: Safety and recoverability
+  weight: 0.25
+- name: Evidence-driven correctness
+  weight: 0.25
+- name: Executor/session decoupling
+  weight: 0.2
+- name: Local testability without external services
+  weight: 0.15
+- name: Clear CLI/report UX
+  weight: 0.15
+exit_conditions:
+- All MVP acceptance criteria pass locally.
+- No command path relies on OpenCode/Goose/Codex private session memory for correctness.
+- Graphify and agentmemory are optional integrations with graceful degradation.
+- Working tree is clean with a verified commit.

memento_lifecycle-0.1.0/.ouroboros/seeds/memento-v1.seed.yaml

@@ -0,0 +1,139 @@
+metadata:
+  name: memento-v1-executor-routing
+  version: 1.0.0
+  created_at: '2026-05-12T13:59:28Z'
+  origin: hermes-assisted-ouroboros-fallback
+  phase: v1
+  depends_on:
+  - memento-mvp
+  ambiguity_score: 0.14
+  project: memento
+goal: 'Implement production-usable v1 executor routing: real Codex CLI and Aider adapters, isolated worktree dispatch,
+  post-dispatch Graphify checkpoints, memory-informed routing, graph-aware risk adjustment, and auditable route
+  decisions.'
+constraints:
+- Keep Memento as the lifecycle source of truth for runs, sessions, plans, tasks, dispatches, evidence, and verification
+  decisions.
+- Do not depend on executor-native private sessions for correctness, retry, recovery, or progress reporting.
+- Executor summaries, reasoning traces, and self-assessments are advisory and cannot independently satisfy task
+  acceptance.
+- Preserve safety gates for destructive git operations, credentials, production/release actions, and forbidden paths.
+- Apply secret redaction and forbidden-path policies before storing evidence payloads, command output, diffs, or
+  artifacts.
+- Graphify must be checkpoint-driven by default; continuous watch is optional and must not be required for correctness.
+- agentmemory writeback must store only durable reusable lessons, not temporary task progress, raw logs, commit
+  hashes, PR numbers, or raw graph payloads.
+- External executor attempts must run in isolated worktrees by default unless explicitly configured otherwise.
+- Codex/Aider self-reports must be independently verified by Memento before task acceptance.
+- Router may strengthen verification policy using Graphify/agentmemory but must not weaken required checks without
+  explicit approval.
+- OpenCode remains manual_or_experimental and is not a default automatic executor in v1.
+scope:
+  in:
+  - Real Codex CLI adapter with healthcheck, prompt rendering, timeout, result collection, and structured failure
+    handling.
+  - Real Aider adapter for scoped edits with allowed-files/relevant-files enforcement.
+  - Worktree isolation for external dispatch attempts, including partial diff quarantine.
+  - Graphify post-dispatch update after verified code/docs changes.
+  - agentmemory-informed route-task using repo conventions, known pitfalls, and executor history summaries.
+  - Graph-aware risk adjustment using graph staleness, centrality/god-node signals, touched communities, and affected
+    files.
+  - Auditable routing decisions and user override handling with hard safety preservation.
+  out:
+  - Goose/SWE-agent/OpenHands production adapters.
+  - Automatic confidence-weighted performance aggregation beyond simple memory recall.
+  - Multi-executor competition.
+  - Deep graph-derived task decomposition.
+acceptance_criteria:
+- name: Codex CLI adapter
+  description: Memento can healthcheck Codex, render a context bundle into a one-shot prompt/file invocation, run
+    with timeout in an isolated worktree when enabled, collect changed files/output/exit code, and record evidence.
+  verification: Mocked tests cover success, timeout, process error, no-change, and verification-failed paths; optional
+    live smoke is gated by availability.
+- name: Aider adapter
+  description: Memento can route scoped edit tasks to Aider with allowed/relevant files and collect results without
+    trusting Aider self-report.
+  verification: Tests confirm broad tasks are rejected for Aider when file scope is unclear and scoped tasks produce
+    invocation metadata/results.
+- name: Isolated worktree dispatch
+  description: External executor dispatches use isolated worktrees by default and never corrupt the canonical workspace
+    with unverified partial work.
+  verification: A failing external dispatch leaves canonical workspace clean and stores partial diff as quarantined
+    advisory evidence.
+- name: Post-dispatch Graphify checkpoint
+  description: After verified executor work changes code or docs, Memento triggers a Graphify checkpoint/update
+    according to policy and attaches graph evidence.
+  verification: Mock Graphify runner records graph_update evidence, graph state current/stale/update_failed, and
+    report status after dispatch verification.
+- name: Memory-informed routing
+  description: Router uses agentmemory recall for repo conventions, known pitfalls, verification commands, and executor
+    suitability when ranking candidates.
+  verification: Fake memory adapter changes routing reasons/score and adds verification command suggestions without
+    weakening required checks.
+- name: Graph-aware risk adjustment
+  description: Router uses Graphify impact signals to adjust task risk, context profile, verification strength,
+    and approval requirements.
+  verification: A task touching a mocked god node or multiple communities is promoted to higher risk and requires
+    stronger verification or approval.
+- name: Manual override with safety preservation
+  description: User-specified executor overrides are honored only if hard safety/capability constraints still pass.
+  verification: Tests show an override is rejected when sandbox/forbidden-path requirements cannot be satisfied
+    and the rejection reason is recorded.
+- name: Actionable retry/fallback
+  description: Timeouts, process errors, missing context, no changes, unsafe diffs, and verification failures map
+    to policy-driven retry, fallback, repair task, Hermes escalation, or blocked state.
+  verification: Unit tests verify failure category to next-action mapping and audit events.
+- name: v1 verification suite
+  description: v1 functionality passes local tests and smoke gates.
+  verification: Run pytest, ruff, compileall, doctor, sample-smoke, and mocked Codex/Aider/Graphify adapter tests
+    successfully.
+ontology_schema:
+  name: MementoV1ExecutorRouting
+  entities:
+  - name: ExecutorAdapter
+    fields:
+    - name
+    - capabilities
+    - health
+    - prepare
+    - dispatch
+    - collect
+    - cancel
+  - name: IsolatedWorktree
+    fields:
+    - path
+    - base_ref
+    - dispatch_id
+    - status
+    - cleanup_policy
+  - name: GraphCheckpoint
+    fields:
+    - id
+    - trigger
+    - status
+    - graph_state
+    - changed_files
+    - artifact_refs
+  - name: MemoryRecall
+    fields:
+    - repo_profile
+    - known_pitfalls
+    - executor_history
+    - verification_commands
+evaluation_principles:
+- name: Executor isolation
+  weight: 0.25
+- name: Independent verification
+  weight: 0.25
+- name: Routing explainability
+  weight: 0.2
+- name: Graph/memory usefulness
+  weight: 0.15
+- name: Failure handling quality
+  weight: 0.15
+exit_conditions:
+- Codex/Aider adapters are implemented with mocked tests and optional live smoke.
+- External executor partial work is quarantined until verified.
+- Graphify post-dispatch checkpointing is available and optional-failure safe.
+- Route decisions are auditable and explainable.
+- Working tree is clean with a verified commit.

memento_lifecycle-0.1.0/.ouroboros/seeds/memento-v2.seed.yaml

@@ -0,0 +1,134 @@
+metadata:
+  name: memento-v2-learning-graph
+  version: 2.0.0
+  created_at: '2026-05-12T13:59:28Z'
+  origin: hermes-assisted-ouroboros-fallback
+  phase: v2
+  depends_on:
+  - memento-mvp
+  - memento-v1-executor-routing
+  ambiguity_score: 0.16
+  project: memento
+goal: 'Implement v2 learning and graph-aware orchestration: Goose and SWE-agent adapters, confidence-weighted executor
+  performance memory, automatic verification enrichment, graph-derived task decomposition support, partial-work
+  repair workflows, and budget-aware multi-attempt fallback.'
+constraints:
+- Keep Memento as the lifecycle source of truth for runs, sessions, plans, tasks, dispatches, evidence, and verification
+  decisions.
+- Do not depend on executor-native private sessions for correctness, retry, recovery, or progress reporting.
+- Executor summaries, reasoning traces, and self-assessments are advisory and cannot independently satisfy task
+  acceptance.
+- Preserve safety gates for destructive git operations, credentials, production/release actions, and forbidden paths.
+- Apply secret redaction and forbidden-path policies before storing evidence payloads, command output, diffs, or
+  artifacts.
+- Graphify must be checkpoint-driven by default; continuous watch is optional and must not be required for correctness.
+- agentmemory writeback must store only durable reusable lessons, not temporary task progress, raw logs, commit
+  hashes, PR numbers, or raw graph payloads.
+- Goose and SWE-agent adapters must remain capability-gated and may be disabled when healthcheck or sandbox requirements
+  are not met.
+- Executor performance memories must be confidence-weighted, aggregated, and decayed; one-off observations must
+  not dominate routing.
+- Graph-derived task decomposition must be advisory and reviewed against canonical plan/task graph constraints before
+  dispatch.
+- Budget policies must cap attempts, runtime, executor cost, and Graphify deep/semantic updates.
+scope:
+  in:
+  - Goose adapter as experimental OpenCode-like general agent worker with healthcheck and headless/API/process mode
+    detection.
+  - SWE-agent adapter for sandboxed issue repair and test-driven bugfix tasks.
+  - Confidence-weighted executor performance memory with aggregation and decay.
+  - Automatic verification policy enrichment using agentmemory and Graphify signals.
+  - Graph-derived candidate task/dependency suggestions from relevant subgraphs and communities.
+  - Repair-task creation from rejected/partial dispatch evidence.
+  - Budget-aware multi-attempt retry/fallback policies.
+  out:
+  - OpenHands worker pool.
+  - Multi-executor competition/ranking with patch comparison.
+  - Team/CI integration as first-class source of truth.
+  - Fully autonomous graph rewrite of canonical plans without review.
+acceptance_criteria:
+- name: Goose adapter
+  description: Memento can register Goose as an experimental executor, healthcheck it, render context, run/collect
+    when enabled, and mark it unavailable/manual when healthcheck fails.
+  verification: Mocked tests cover available, auth failure, non-headless limitation, timeout, and structured failure
+    result.
+- name: SWE-agent adapter
+  description: Memento can route issue-repair/test-driven-fix tasks to SWE-agent only when sandbox requirements
+    are satisfied.
+  verification: Tests verify sandbox-required routing, issue spec rendering, result collection, and fallback when
+    sandbox unavailable.
+- name: Confidence-weighted executor memory
+  description: Executor performance observations are aggregated by repo, task kind, size, graph impact, and executor;
+    confidence increases with repeated observations and decays over time.
+  verification: Tests show one success is weak signal, repeated successes increase score, recent failures reduce
+    score, and stale data decays.
+- name: Verification enrichment
+  description: Memento automatically strengthens verification policies using memory and graph signals, such as adding
+    smoke tests for affected API/UI contracts or full tests for god-node changes.
+  verification: Tests confirm enrichment adds checks with reasons and never removes or weakens required checks without
+    approval.
+- name: Graph-derived decomposition suggestions
+  description: Memento can use Graphify communities, high-centrality nodes, affected files, and surprising connections
+    to propose task splits/dependencies for review.
+  verification: Given a mocked graph, the planner suggests candidate tasks/dependencies and records them as proposals,
+    not silently accepted canonical tasks.
+- name: Partial-work repair workflow
+  description: Rejected or partially verified dispatches can create repair tasks linked to quarantined diff/evidence
+    and failed requirements.
+  verification: Tests produce a repair task from failing test evidence and ensure downstream tasks remain blocked
+    until repair is accepted.
+- name: Budget-aware fallback
+  description: Routing and retry respect configured budgets for time, attempts, executor count, and Graphify semantic
+    updates.
+  verification: Tests show budget exceeded leads to escalation/blocked state with actionable reasons.
+- name: v2 verification suite
+  description: v2 features pass local tests including mocked Goose/SWE-agent/memory/Graphify scenarios.
+  verification: Run pytest, ruff, compileall, doctor, sample-smoke, and v2 adapter/router tests successfully.
+ontology_schema:
+  name: MementoV2LearningGraph
+  entities:
+  - name: ExecutorPerformanceMemory
+    fields:
+    - executor
+    - repo
+    - task_kind
+    - graph_impact
+    - success_count
+    - failure_count
+    - confidence
+    - decay
+  - name: VerificationEnrichment
+    fields:
+    - added_checks
+    - reasons
+    - source_memory_refs
+    - source_graph_refs
+  - name: GraphTaskProposal
+    fields:
+    - proposed_tasks
+    - dependencies
+    - graph_basis
+    - review_status
+  - name: RepairTask
+    fields:
+    - source_dispatch_id
+    - failed_requirements
+    - quarantined_diff_ref
+    - verification_policy
+evaluation_principles:
+- name: Learning quality without memory pollution
+  weight: 0.25
+- name: Graph-aware orchestration usefulness
+  weight: 0.2
+- name: Adapter safety and capability gating
+  weight: 0.2
+- name: Budget/fallback reliability
+  weight: 0.2
+- name: Recoverability from failures
+  weight: 0.15
+exit_conditions:
+- Goose and SWE-agent adapters are available behind health/capability gates.
+- Performance memory aggregation/decay affects routing in tests.
+- Verification enrichment is explainable and policy-safe.
+- Graph-derived task suggestions are reviewable proposals.
+- Working tree is clean with a verified commit.