memory.md

Project Memory

OpenSymphony project memory turns completed Linear work into durable development context. During opensymphony run, terminal issue transitions are captured automatically when memory auto-capture is enabled. The capture uses Linear issue narrative, active Workpad content, issue hierarchy, milestones, GitHub PR descriptions, reviews, checks, and source refs. It writes private issue capsules under .opensymphony/memory/, updates a DuckDB index, evolves .opensymphony/memory/memory.yaml, and syncs stable topics into public docs.

The operator projection reports memory scope, source freshness, degradation, and overlay provenance without exposing memory grants or tokens. Memory availability does not grant filesystem access.

Related specifications:

• OKF Memory System Specification describes how the Markdown memory corpus should evolve into Open Knowledge Format bundles.
• Knowledge Graph Specification describes the client-side graph explorer for those bundles.

Rationale and Model

Linear remains OpenSymphony's short-term planning and coordination surface, but completed issues still carry implementation knowledge that should survive queue cleanup and archival. GitHub PRs preserve code review history, and Workpad comments preserve useful audit details, but neither is a convenient component-oriented project memory on its own.

OpenSymphony memory is the completed-work distillation of what mattered: the intent, shipped outcome, decisions, validation evidence, relevant review feedback, follow-ups, risks, and documentation impact. Implementation agents should keep their focus on code, validation, PRs, and Workpad accuracy; long-term memory is produced by capture and docs sync rather than by ad hoc edits during ordinary feature work.

The memory system has two different outputs:

• Issue capsules record what happened for one completed Linear issue. They are compact source-referenced closeout documents, not run transcripts.
• Topic docs describe what is now true about a subsystem. They capture the current model, invariants, gotchas, and recent changes without requiring readers to know which issue introduced the knowledge.

OKF Bundle Compatibility

OpenSymphony treats OKF as the portable Markdown contract for memory, not as a replacement for the current local store. The logical bundle layout follows docs/specs/okf-memory-spec.md:

bundle-root/
  index.md
  log.md
  projects/
  milestones/
  issues/
  areas/
  repositories/
  code/
  runs/
  references/

The current .opensymphony/memory/ paths stay in place for this compatibility slice. Issue capsules map to issues/<issue>.md, milestone nodes map to milestones/<slug>.md, generated topic docs map to areas/<slug>.md, and repository memory remains a facet under repositories/ rather than the root taxonomy.

Every parsed OKF concept requires YAML frontmatter with a non-empty type and a contained bundle-relative Markdown path. Existing legacy top-level fields such as issue, milestone, linear_url, areas, repository, prs, source_refs, and docs_sync are preserved as data during parse/render. The parser also projects those fields into opensymphony extension metadata: visibility, concept kind, scope refs, source refs, and docs-sync state. Unknown frontmatter is kept in the raw frontmatter map so future writers can round-trip documents they do not fully understand. Writers emit canonical YAML and do not preserve the original frontmatter field order or whitespace.

opensymphony memory lint --okf [bundle-root] validates an OKF bundle from the CLI, and the memory MCP admin path accepts the equivalent memory.lint request with okf plus bundleRoot arguments. A user-supplied bundle root is canonicalized and must stay inside the repository root, matching the containment policy used by other memory admin file arguments. When no bundle root is provided, linting uses the configured memory root.

opensymphony memory export-okf --visibility public|private [--output DIR] exports the configured memory root as a directory bundle. The output directory defaults to okf-export-{visibility} under the repository root when omitted and must be new or empty so stale private files cannot survive a public export. Export writes into a repository-contained staging directory first, runs OKF lint on the staged bundle, and only then promotes the completed bundle to the requested output path. If final promotion fails, OpenSymphony preserves the lint-clean staged bundle for recovery and restores the previous empty output directory when possible. Public export skips private concepts and fails if any remaining public concept still references private comments, private memory paths, or private source snapshots. Private export can include private concepts but still keeps normal OKF lint errors fatal except for visible links back into the private memory store, which are expected in private round-trip bundles.

The public export redaction scan is deliberately narrow and explicit: it treats linear:comment:, .opensymphony/memory/issues, .opensymphony/memory/source*, .opensymphony/memory/snapshot*, and their Windows-path variants as private material when they appear in exported public concepts. The scan uses the same markdown-visible text extraction as private memory link linting, so fenced code blocks, inline code spans, escaped text, and HTML comments do not create public export false positives.

The memory MCP admin surface exposes the same export operation as memory.export_okf with visibility (public or private) and optional output arguments. It uses the same repository containment, staging, lint, and public redaction checks as the CLI command.

opensymphony memory import-okf <bundle-root> [--force] validates an OKF directory bundle, copies its Markdown concepts into the configured memory root without rewriting frontmatter, and rebuilds the derived DuckDB catalog from the imported bundle. The import source and target memory root are canonicalized, checked against the repository containment policy, and rejected when they overlap. Import preflights the full copy set before writing so predictable target conflicts do not leave partially imported Markdown files. Existing Markdown files are not overwritten unless --force is supplied. Because import-okf restores both public and private bundles, visible private memory links are allowed during import and preserved in the copied Markdown. Unknown concept types, unknown frontmatter fields, missing optional fields, broken links, and missing generated indexes are warning-level import inputs; malformed concepts remain errors with file paths in the diagnostic.

Import is not transactional after the preflight succeeds. A filesystem write or DuckDB reindex failure can leave already-copied Markdown files in the memory root. Fix the underlying failure, inspect the partially copied files, and rerun with --force only when replacing those files is intentional.

The memory MCP admin surface exposes the same import operation as memory.import_okf with bundleRoot and optional force arguments. Prefer the CLI or MCP admin tools for normal maintenance; direct file or DuckDB inspection is an offline fallback for recovery and diagnostics only.

OKF lint diagnostics are intentionally actionable. Errors cover missing or invalid concept frontmatter, missing type, malformed reserved files, containment failures, and public-export leaks of private memory. Warnings cover missing recommended fields, unknown types, broken Markdown links, wiki-only links without Markdown equivalents, missing generated indexes, missing citations for source-backed claims, and unknown OKF versions. Info diagnostics call out synthesized title/description data, retained legacy fields, and OpenSymphony extension metadata. Warning-level findings remain nonfatal; private-data leakage and containment breakage are reported as errors.

Migration is intentionally incremental:

• Phase 1 enriches and parses existing documents as OKF concepts while keeping legacy paths and fields.
• Phase 2 can mirror or move documents into the final bundle layout and rebuild the catalog from OKF concepts.
• Phase 3 can expose graph, hosted import/export, and visibility-filtered APIs from the OKF-derived catalog.

The memory graph projection is derived from the OKF catalog, not from client edits. Graph snapshots include bundle, directory, concept, tag, resource, citation, source-ref, and community nodes plus derived containment, Markdown, external, citation, tag, resource, scope, source-support, and same-resource edges. Broken Markdown links are kept as unresolved edges. Snapshot metrics report orphan, broken-link, stale-concept, and warning counts, while node metrics report degree, global normalized centrality across all graph node kinds, bridge score, and community ID. Community labels prefer concept areas, then tags, directories, and concept type. Each concept is assigned to exactly one deterministic community; when multiple areas are present the sorted first area wins, and tag fallback uses frontmatter order. Tags, citations, and source refs are excluded from community membership by default and can be included with the memory graph endpoint query flags. Those flags also parameterize node community IDs and bridge scores because the community membership input set changes with the query. Community IDs are stable grouping keys, not graph node IDs; community graph nodes are separately namespaced with community:<id>.

No graph-library dependency is currently selected for memory graph extraction: the shipped backend work only derives deterministic catalog relationships and metadata communities. Add a graph library when the server owns true clustering or graph algorithms beyond these deterministic DTO metrics.

The default visibility posture is private memory with optional public docs. Private capsules may include Linear comments, review context, and source snapshots, while public docs should contain public source refs such as issue identifiers, PR URLs, and commit SHAs. Public docs must not link directly to private capsule paths. Public memory is supported only by explicit configuration, and generated indexes such as DuckDB should remain local unless a project deliberately publishes them.

Generated memory indexes/log.md output groups entries under ## YYYY-MM-DD headings with newest dates first. The date comes from indexed completion time when available, then capture time, and finally a stable ISO sentinel for malformed legacy rows so regeneration is deterministic.

Areas bridge issue memory and topic docs. Area inference uses Linear narrative, labels, milestones, active Workpad content, PR narrative, review summaries, and existing learned aliases in .opensymphony/memory/memory.yaml. GitHub changed files are indexed for path-based lookup, but they do not create areas or appear in capsule or docs prose. Merge SHAs are immutable audit refs, not inference signals.

The CLI remains useful for setup, historical backfill, inspection, and manual operator actions:

opensymphony memory init
opensymphony memory capture COE-123
opensymphony memory context --issue COE-456
opensymphony memory brief COE-123
opensymphony memory related --area openhands-runtime
opensymphony memory sync-docs --since-last-sync
opensymphony memory serve --addr 127.0.0.1:8765
opensymphony memory export-okf --visibility public --output public-okf
opensymphony memory import-okf public-okf
opensymphony linear archive --issues COE-123

Use --dry-run on write commands when you want a non-writing preview.

Configuration

config.yaml controls run-loop automation:

memory:
  auto_capture: true
  auto_archive: false
  serve: true
  bind: 127.0.0.1:0

auto_capture defaults to true. auto_archive defaults to false; when it is enabled, OpenSymphony archives only after fresh capture succeeds with no blocking warnings. serve starts the local memory server during opensymphony run when memory is initialized. The default bind address selects an available loopback port once, records it in <workspace-root>/.opensymphony-memory-bind.json, and reuses that exact port on later starts. This keeps the endpoint stable for an authenticated parent conversation recovered after daemon restart; startup fails if the recorded port cannot be rebound rather than rotating the conversation's endpoint. Workers receive the resulting MCP endpoint through OPENSYMPHONY_MEMORY_ENDPOINT. Workers receive only the normal read token; admin tools require a separate OPENSYMPHONY_MEMORY_ADMIN_TOKEN.

Persistent Code Graph indexing

POST /api/v1/code/repos/{repo_id}/index and the native code_index_repo command build a bounded repository snapshot for the target branch recorded in WORKFLOW.md (default develop). The server resolves the repository root and commit; clients cannot provide arbitrary roots. Files are read from Git tree and blob objects, so indexing does not execute target-repository code.

Snapshot membership is immutable and keyed by repository, commit, and path. Documents, symbols, edges, diagnostics, and skipped coverage are persisted in batches. A later commit reuses unchanged membership, parses changed or added paths, and marks deleted current rows stale without rewriting older revisions. One process-wide index writer lock serializes concurrent indexing requests while DuckDB read paths remain usable. The gateway journals accepted/progress, completed, unavailable, and failed outcomes; code_graph_updated is emitted only after a completed snapshot is available.

This index is a shared target-branch baseline. It must not be treated as the live code state of an issue workspace; workspace overlays provide that view.

An empty DuckDB is a supported starting state. The gateway advertises the configured repository with zero coverage, allowing the web or desktop Code Graph surface to start indexing directly. The surface renders accepted and progress coverage, skipped-file diagnostics, retryable failures, and refreshes from code_graph_updated; during accepted/progress work with no event delivery, the shell polls repository summaries and recognizes a newly indexed baseline. Production web requests use HTTP and packaged desktop requests use the Tauri-native code_index_repo command against the same report contract.

Initialize the shared memory policy and learned ontology file once:

opensymphony memory init

This creates .opensymphony/memory/memory.yaml and updates .gitignore so only that config is tracked. Capsules, indexes, DuckDB, source snapshots, and automation logs remain local runtime artifacts.

The config is not a hand-maintained docs map. It is a policy plus learned structure file that capture can evolve as more work lands:

memory_root: .opensymphony/memory
visibility: private
index_path: .opensymphony/memory/memory.duckdb
confidence_threshold: 75
source_snapshots: hashes
markdown_indexes: true
docs:
  public_root: docs
  default_visibility: public
  deny_private_links: true
areas:
  openhands-runtime:
    title: OpenHands Runtime
    docs_target: docs/openhands-agent-server.md
    visibility: public
    status: stable
    confidence: 85
    aliases:
      - OpenHands Runtime
    source_refs:
      docs:
        - docs/openhands-agent-server.md
      linear_labels:
        - runtime
      linear_issues:
        - COE-123

memory init seeds stable areas from existing top-level docs/*.md files when they exist. It does not scan docs/tasks, README.md, Cargo files, source files, or GitHub changed-file lists to create docs topics. When no docs exist, the config is still valid and starts with an empty areas map.

Capture Evidence

Live capture requires Linear access from WORKFLOW.md and uses GitHub PR discovery by default through gh. For each issue, OpenSymphony reads:

• Linear title, description, labels, state, URL, milestone, parent, children, and active Workpad comment
• GitHub PR title, body, branch, checks, review discussion summaries, commits, merge SHA, and changed files

Area inference treats Linear labels named area:<slug> as canonical. Existing label aliases and narrative evidence from Linear and GitHub still work as fallbacks. Merge SHA is not used for inference or search; it is stored only under source_refs as the immutable audit pointer to the exact merged code state. GitHub changed files are indexed for later lookup such as "which issues touched this file?", but they are not rendered into capsules or docs and do not infer areas.

Selecting a parent issue also captures its child issue closure. Capsules link parents, children, and milestones so the Obsidian graph shows the work structure.

Linear and GitHub are part of the normal live flow. A missing WORKFLOW.md, invalid Linear config, missing issue, Linear API failure, or failing gh command fails capture. Use --no-github only for unusual non-PR work.

Import and Backfill

memory import is for deterministic backfills, migrations, tests, or external exports. It is not the normal path.

opensymphony memory import --source-file completed.yaml
opensymphony memory import COE-123 --source-file completed.yaml
opensymphony memory import --issue-range COE-120..COE-130 --source-file completed.yaml

Top-level source YAML fields:

issues: []
prs: []
overrides: {}

Important issue fields:

issues:
  - id: issue-id
    identifier: COE-123
    title: Issue title
    url: https://linear.app/example/issue/COE-123
    description: Optional issue description
    state: Done
    milestone: M3
    milestone_id: milestone-id
    parent:
      identifier: COE-100
      title: Parent title
    children:
      - identifier: COE-124
        title: Child title
    labels:
      - runtime
    comments:
      - id: comment-id
        author: username
        body: "Decision or summary text"
        updated_at: 2026-03-25T22:05:00Z
        source: linear:workpad
    linked_prs:
      - 456

Important PR fields:

prs:
  - number: 456
    title: COE-123 implement reconnect recovery
    url: https://github.com/example/repo/pull/456
    branch: coe-123-reconnect
    body: Pull request summary
    merge_sha: abcdef1234567890
    changed_files:
      - path: crates/opensymphony-openhands/src/client.rs
        change_kind: modified
    checks:
      - name: cargo test
        conclusion: success
    reviews:
      - reviewer: reviewer
        state: APPROVED
        disposition: Looks correct.

All fields except issues[].identifier and prs[].number are optional.

Query and Docs Sync

Useful read commands:

opensymphony memory status
opensymphony memory context --issue COE-456
opensymphony memory brief COE-123
opensymphony memory related --area openhands-runtime
opensymphony memory related --paths crates/opensymphony-openhands
opensymphony memory search "reconnect recovery"
opensymphony memory docs --area openhands-runtime

memory context is a pre-implementation context compiler, not a capture command. It fetches live Linear facts when available, excludes the current issue capsule, and selects captured memory from deterministic buckets: explicit includes, blocking predecessors, completed children, completed siblings, path matches, and canonical area matches. It strips each selected brief's Documentation impact section and appends one deduplicated section at the end. When opensymphony run starts a worker, it asks the supervised memory server for the same style of kickoff bundle and writes it to .opensymphony/generated/memory-context.md inside the issue workspace. If the server is disabled, the runner falls back to direct local memory reads.

Read commands open the DuckDB index in read-only mode and do not run migrations. Startup and write paths own schema creation or migration.

When central configuration is active, one supervised memory server owns one instance-wide catalog. Repository inventory entries are registered in that catalog by canonical repository ID and exact checkout commit. Policy files, public documentation, portable OKF bundles, and legacy stores remain repository-owned sources; private issue, project, milestone, and cross- repository records remain in the instance catalog. Source registration is a startup/write operation and records its status and generation in DuckDB, while ordinary MCP reads only inspect the existing schema. Code-intelligence lookups use the registered canonical repository ID rather than a caller-supplied local path.

Managed local OpenHands workers receive the memory endpoint and their per-conversation scoped read grant through the worker environment. The process-wide server read token is never placed in the shared managed-server environment, so one worker cannot bypass its grant by reading that token from a shared agent-server process.

memory serve exposes the memory command set through a local MCP-style Streamable HTTP JSON-RPC endpoint at /mcp. CLI commands call that endpoint when OPENSYMPHONY_MEMORY_ENDPOINT is set; otherwise they use offline direct mode. Read tools are memory.context, memory.search, memory.related, memory.brief, memory.docs, memory.status, and, when code_intel.ast.enabled is true, code.ast.status, code.ast.outline, code.ast.symbols, code.ast.references, code.ast.context, and code.ast.diagnostics. code.ast.query is also local read-only by default, but requires the admin token when an admin token is configured so hosted or token-gated deployments can restrict ad hoc query execution. Admin tools are memory.capture, memory.sync_docs, memory.lint, memory.reindex, memory.export_okf, memory.import_okf, and memory.ingest_code_intel; these require OPENSYMPHONY_MEMORY_ADMIN_TOKEN or --admin-token on opensymphony memory serve. If an admin token is configured without a separate read token, the admin token also protects read tools. Worker-grant capability checks follow that server access decision: a local read-only code.ast.query does not require an administrative grant capability, while a configured admin token still gates the request at the server boundary. On a supervised server with a configured workspace root, unauthenticated unscoped reads are still rejected as worker requests; an operator using the configured read or admin bearer may perform ordinary read calls without a worker grant. Worker calls remain bound to a server-issued project-set, project, work-item, canonical-repository, visibility, and capability grant. Explicit filters can only narrow those claims. all_accessible is therefore bounded by the grant, and an authorized sibling repository must be named explicitly. Ordinary worker grants have no administrative capability. Persisted sibling memory and target-branch code use the registered canonical source; AST requests may name that source using the repository alias as well as the legacy repo field; live overlays resolve only the execution repository's verified checkout. A parent integration grant instead contains the exact repository set from its durable runtime envelope. Persisted memory may span that set and the parent plus recorded descendants; all_accessible cannot add another repository or work item. Live overlays resolve only the envelope's active integration checkouts, using their opaque handles, contained relative paths, run and attempt, and target commits. An unrelated managed checkout stays inaccessible even when its repository belongs to the same project. The overlay must match the worker's issue, run, attempt, checkout generation, and target commit. A worker may advance that checkout during its run; strict discovery verifies that the current HEAD descends from the target commit instead of freezing the overlay to the startup HEAD. Each result reports the canonical repository, the revision that actually produced its source path or symbol, freshness, and persisted-versus-live provenance. memory.context builds the agent kickoff bundle. Add --include-code-intel to include code-intelligence artifacts alongside selected memory. For requested Rust paths, OpenSymphony renders Tree-sitter AST summaries, symbols, diagnostics, and a trace section before falling back to repository analysis. Unsupported languages, parser diagnostics, oversized files, and calls without requested paths use the existing CodebaseAnalyzer repository-summary fallback; mixed supported and unsupported requests can include both AST artifacts and fallback artifacts. The trace section records parse/query counts and the fallback reason. The rendered artifact/provider contract is owned by opensymphony_code_intel; memory keeps the legacy CodeIntelIndex and CodeIntelArtifact surface as an adapter around that provider contract instead of requiring code-intelligence providers to import memory internals.

Worker-scoped memory access uses a server-local, non-persisted bearer grant bound to the worker's project-set, project, work item, execution repository, authorized repository set, visibility, run/attempt, and checkout generation. An unchanged leaf claim set may reuse the conversation bearer; a changed leaf run, attempt, binding, target commit, or generation rotates the bearer and requires a fresh leaf conversation. The startup checkout HEAD is retained as capture provenance, not as a live-overlay equality requirement. Durable daemon recovery reconstructs leaf claims from the runtime envelope and forces a fresh leaf conversation when the in-memory registry was replaced. A parent controller instead restores the bearer already held by its persisted OpenHands conversation into the reconstructed registry and verifies the same memory endpoint and workspace before reattachment. A missing or different parent conversation manifest is rejected before a replacement session can launch. Terminal, inactive, and binding-superseded lifecycles issue the stop/cancel fence before revoking the issue grant. Raw bearer tokens are never persisted in manifests or diagnostics. With automatic capture enabled, terminal issues seen at daemon startup remain capture candidates instead of being assumed captured. Subtree cleanup revokes a bearer only when its checkout generation matches the cleanup target. If a newer generation for the same issue already holds the live grant, old-generation cleanup leaves that bearer and its lifecycle state unchanged. This grant applies to direct memory.show capsule reads as well as search, context, brief, related, docs, status, and code-intelligence tools. If the central service stops, the control-plane status is explicitly degraded and scoped worker reads remain blocked; they do not silently fall back to an unrelated repository-local store. Leaf capture reads the immutable runtime envelope for repository ownership and commits, and documentation sync uses that explicit owner. Terminal capture reads those durable envelopes from leaf roots and from the generation-bound parents/<parent-key>/<generation> layout. Completed parent roots remain retained across reconciliation and restart so a transient capture failure cannot erase the repository/run provenance needed for the next attempt. Their descendant leases remain active with the root so leaf cleanup cannot invalidate registered integration worktrees before OSYM-893 records capture acknowledgement and performs ordered cleanup. The run loop records that acknowledgement only after the capture workflow completes for the selected parent. Cleanup first receipts hook execution and detaches the parent integration worktrees, then removes unleased descendants bottom-up and the parent root last. Failure to persist the acknowledgement leaves the capture candidate eligible for retry. For a parent, the capture path also reads validated durable controller state and requires a matching terminal lifecycle. Successful completion additionally requires its final attempt to be passed for the same run and input version, its final evidence to be bound to the same conversation, and its exact repository commit map to equal the runtime envelope. A terminal run manifest or harness success by itself cannot authorize successful parent capture. Failed and canceled controllers receive a repository-neutral parent binding with no verified commit claims so their diagnostics can be captured before the explicit retention policy runs. If restart proves that a parent launch never attached and no run.json exists, the owned parent manifest plus the matching terminal controller supplies only that neutral parent classification; it does not invent run, attempt, command, or commit evidence. The durable binding explicitly marks a parent even when its commit map is empty, so repository-neutral capture cannot inherit a configured default leaf repository. A capture with an actual runtime envelope records one repository-neutral parent-runtime source reference with the durable run and attempt identifiers. Retained legacy run envelopes that lack usable run/attempt provenance are skipped as non-bindable entries during the pre-cleanup scan rather than preventing unrelated terminal captures from completing. The direct code.ast.* tools return JSON with path, line range, content hash, parser version, query-pack version, trace, and truncation metadata for targeted agent inspection. memory.context remains the recommended kickoff path. memory.ingest_code_intel generates code-intelligence artifacts without persistence by default. Admin callers can pass persist=true to write derived DuckDB rows for code documents, symbols, query-pack edges, and parser diagnostics. Persisted rows store metadata, hashes, spans, parser/query-pack versions, freshness, and snippet hashes only; full parse trees and source snippets are rendered from files on demand. Re-ingesting a changed file or a different parser/query-pack version marks older derived rows stale before writing current rows. Commit SHA and dirty-worktree state are stored as provenance on the current rows; a clean re-ingest with identical content, parser version, and query-pack version updates that provenance without reporting phantom stale rows.

Generated, vendor, build, and cache directories are skipped during directory traversal with trace warnings, as are files over code_intel.ast.max_file_bytes. Explicit file requests inside skipped directory names still parse when they pass path containment and resource limits. The AST tools only use built-in pinned grammar crates and never execute target-repo source, build scripts, package manager scripts, tests, or macros. See docs/code-intelligence.md for the operator and agent workflow.

opensymphony memory reindex --from-okf [bundle-root] rebuilds the derived DuckDB catalog from OKF concept documents, defaulting to the configured memory root. Broken links and unknown concept types are indexed as warnings; malformed OKF frontmatter remains fatal because those files are not parseable concepts. The OKF rebuild clears derived GitHub metadata tables (pull_requests, changed_files, checks, and reviews) because OKF concepts do not currently carry that capture-enrichment data.

Docs sync writes stable topic docs by default and prints stat-style output with file paths, line counts, and changed-line totals:

opensymphony memory sync-docs --since-last-sync
opensymphony memory sync-docs --issues COE-123

Candidate or low-confidence areas remain private until later captures raise their confidence. Automation records warnings in .opensymphony/memory/indexes so operators can inspect unresolved capture or docs-sync blockers. When the Linear project overview content is available, OpenSymphony also maintains a managed memory-status section there for capture warnings that need attention.

Archive Guard

Archival is guarded by memory capture. For explicit issues, opensymphony linear archive first performs live Linear and GitHub capture, then archives only eligible issues:

opensymphony linear archive --issues COE-123
opensymphony linear archive --issue-range COE-120..COE-130

An issue is eligible when fresh captured memory exists and has no unresolved capture warnings. --force bypasses the guard for a deliberate operator recovery. To archive from already captured memory without recapturing, use --from-memory.

When managed local OpenHands is configured, the archive command also moves matching conversations into the repo-scoped archived/ store. It first tries the issue workspace's .opensymphony/conversation.json manifest, then scans managed conversation meta.json files for a workspace.working_dir ending in the issue key so repo-scoped active conversations and legacy flat conversations are covered by the same archive operation.

Troubleshooting

• If Linear fails, fix WORKFLOW.md, tracker credentials, or issue selection. Live capture does not fall back to placeholder records.
• If GitHub discovery fails, install/authenticate gh or intentionally rerun with --no-github.
• If docs sync writes no topic docs, inspect .opensymphony/memory/memory.yaml for candidate areas below the confidence threshold.
• Use opensymphony memory capture --help, opensymphony memory import --help, and opensymphony linear archive --help for the current command surface.

Current model

• COE-252 contributed: PR #10: Implement foundation workflow and scheduler contracts
• COE-253 contributed: PR #19: COE-253: OpenHands Runtime Adapter (merge 911b0b4)
• COE-254 contributed: PR #6: COE-254: bootstrap tracker, workspace, and orchestration core
• COE-255 contributed: PR #4: COE-255: add control plane and FrankenTUI slice
• COE-256 contributed: PR #1: COE-257: tighten hosted deployment guidance
• COE-258 contributed: PR #83: Add memory init and mapped docs sync

Important invariants

• Preserve the behavior described in the recent captured changes unless current code and tests show it has changed.
• Use capsule source refs to inspect the original PR or Linear issue when context is ambiguous.

Operational flow

• No generated diagram requested for this sync.

Known gotchas

• No area-specific gotchas were inferred from the selected memory.

Recent changes

• COE-252: Foundation and Contracts
• COE-253: OpenHands Runtime Adapter
• COE-254: Tracker, Workspaces, and Orchestration
• COE-255: Observability and FrankenTUI
• COE-256: Validation and Local Operations
• COE-258: Bootstrap workspace and crate boundaries
• COE-259: Workflow loader and typed config
• COE-260: Domain model and orchestrator state machine
• COE-261: Local agent-server supervisor
• COE-262: REST client and conversation contract
• COE-263: Workspace manager and lifecycle hooks
• COE-264: Linear read adapter and issue normalization
• COE-265: WebSocket event stream, reconciliation, and recovery
• COE-266: Issue session runner
• COE-267: Linear MCP write surface
• COE-268: Orchestrator scheduler, retries, and reconciliation
• COE-269: Control-plane API and snapshot store
• COE-270: Repository harness and generated context artifacts
• COE-271: FrankenTUI operator client
• COE-272: Fake OpenHands server and protocol contract suite
• COE-273: Live local end-to-end suite
• COE-274: CLI packaging, doctor, and local operations docs
• COE-277: Implement hierarchy-aware task selection
• COE-280: Support workflow-owned OpenHands auth, provider, and launcher overrides at runtime
• COE-281: Support path-bearing OpenHands base URLs and MCP config at runtime
• COE-282: Support workflow-owned OpenHands conversation reuse policy at runtime
• COE-284: Add orchestrator run command to CLI and make it installable
• COE-287: Add opensymphony debug command for conversational session debugging
• COE-294: Detect LLM config changes and rehydrate conversations with updated env vars
• COE-382: Add supply-chain and security audits to CI
• COE-383: Decompose oversized session and TUI modules into focused submodules
• COE-384: Expand error-path tests for Linear client and workspace hooks
• COE-385: Resolve runtime tracking TODO in OpenHands session runner
• COE-386: Wire cargo-llvm-cov coverage reporting and regression floor into CI
• COE-387: Audit tracing spans and diagnostics for secret leakage
• COE-389: Current Gateway Inventory And Vocabulary
• COE-390: Gateway Schemas And Stream Feasibility
• COE-391: Gateway Module, Capabilities, And Dashboard Snapshot
• COE-392: Task Graph, Run Detail, File, And Diff Read APIs
• COE-393: Event Journal And Stream Broker
• COE-394: Frontend Workspace And Shared Schemas
• COE-395: Planning Artifact Schema And Session Service
• COE-396: Action Receipts And Initial Run Actions
• COE-397: Gateway API Client, Transport Adapters, And Reducers
• COE-398: Tauri Shell And Security Capabilities
• COE-399: Linear Read Coverage And Task Graph Cache
• COE-400: OpenHands Event Normalization And Runtime Mirror
• COE-401: Web App Entry And Deployment Modes
• COE-402: App Shell, Dashboard, Task Graph, And Run Views
• COE-403: Terminal And Log Renderer Prototype
• COE-404: Desktop Connection Profiles And Daemon Management
• COE-405: Linear Milestone, Issue, And Sub-Issue Mutations
• COE-406: Repository, Linear, And Research Analysis
• COE-407: Browser Transport And Remote Stream Protocols
• COE-408: Harness Adapter And Capability Model
• COE-409: Desktop Settings, Keychain, And Native Actions
• COE-410: Desktop Local Stream Optimization
• COE-411: Task Graph Editor And Runtime Overlay UI
• COE-412: Runtime Timeline And Terminal/Log Association
• COE-413: Implementation Plan Generator Stage
• COE-414: Diff, Validation, Approval, And Run Action Views
• COE-415: Milestone, Issue, And Sub-Issue Compiler
• COE-416: Dependency Graph And Plan Checks
• COE-417: Planning Workspace UI
• COE-419: Hosted Auth Placeholders And Web Parity
• COE-423: Model And Credential Settings
• COE-425: OpenHands Subscription Credential Adapter
• COE-426: Codex App-Server Prototype And Benchmarks
• COE-428: Model Configuration UI And Routing Metadata
• COE-429: Codex Approvals And Cross-Harness Routing
• COE-434: Long-running harness liveness and scheduler/runtime ownership contract
• COE-435: Long-running run observability fixtures and client-facing diagnostics
• COE-448: Multi-repo memory server and deterministic context
• COE-449: Desktop alpha recovery: replace stubs with functional app
• COE-452: DuckDB Prebuilt Developer Build Mode
• COE-453: Non-Interactive Init For Automation
• COE-454: OKF Bundle Schema And Legacy Capsule Mapping
• COE-456: OKF Writer, Lint, And Migration Fixtures
• COE-458: Catalog Reindex And Query Compatibility From OKF
• COE-460: OKF Export, Import, And Visibility Boundaries
• COE-461: Memory Graph DTOs And Gateway Endpoints
• COE-463: Docs Sync And MCP Admin Parity For OKF
• COE-464: Graph Extraction, Metrics, And Community Pipeline
• COE-465: Shared Graph Frontend Package And Reducers
• COE-467: Three.js Graph Renderer And Worker Layouts
• COE-468: Concept Inspector, Search, Filters, And Accessibility Fallback
• COE-469: Live Memory Graph Integration And Privacy Gates
• COE-471: Graph Scale, Visual Regression, And Web/Desktop Hardening
• COE-473: Desktop task graph dependency and run detail parity
• COE-475: ChatGPT OAuth For Codex Harness
• COE-476: Codex Production Harness Enablement
• COE-478: Harden model profile storage and validation follow-ups
• COE-479: Codex Debug Session Resume
• COE-480: Run Detail Metrics And Density
• COE-481: Model Configuration Codex Subscription Follow-Up
• COE-482: TUI Codex Token Usage Accounting
• COE-483: Codex Event Content Summaries
• COE-484: Desktop Live Snapshot And Run Detail Refresh
• COE-485: Harden desktop live event resumption and refresh failure visibility
• COE-486: Harness Interrupt Contract And Run Diagnostics
• COE-487: Desktop Run Detail TUI Parity
• COE-488: Lazy Desktop Launcher Command
• COE-489: OpenHands Agent-Server Interrupt Adapter
• COE-490: Codex App-Server Turn Interrupt Adapter
• COE-491: Desktop Run Detail Action Wiring And Cleanup
• COE-492: Merging Supersedes Human Review Polling
• COE-493: Desktop Operations Integration Hardening
• COE-494: Project Metadata For Operator Issue Snapshots
• COE-495: FrankenTUI Project Headers And Dependency Gutter
• COE-496: Desktop Project Grouping And Collapse
• COE-497: Project Grouping Integration Hardening
• COE-498: Tree-sitter Provider Skeleton And Rust Parsing
• COE-499: Memory Context AST Provider Integration
• COE-500: Query Packs For Supported Agent Languages
• COE-501: Code Intelligence Persistence And Ingestion
• COE-502: Read-Only AST MCP And CLI Tools
• COE-503: Code Intelligence Performance Docs And Hardening
• COE-504: Linear Polling And Rate-Limit Recovery
• COE-505: Add scheduler-side Codex stdio interrupt channel
• COE-506: Invert CodeIntelIndex trait ownership after AST memory integration
• COE-507: Deduplicate query-pack assets for grammar variants
• COE-508: Cache code-intel parsers and compiled query packs
• COE-520: Route desktop Knowledge Graph through native gateway commands
• COE-521: Workflow Target Branch Model And Init Customization
• COE-522: Init Target Branch Prompt And Flag
• COE-523: Update Workflow Settings Mode
• COE-524: Template Docs And Settings Hardening
• COE-525: Desktop Installer Contract And Release Metadata
• COE-526: Desktop Release Bundle Pipeline
• COE-527: Source Build Fallback And Prerequisites
• COE-528: App Download Install And Launch Flow
• COE-529: Desktop Auto-Update Flow
• COE-530: Installer Docs And End-To-End Validation
• COE-531: Workspace Shell Graph Hero And Surface State
• COE-532: Symbol Identity Container Chain And Code Read Model
• COE-533: Code Graph DTOs Gateway Routes And Native Commands
• COE-534: Code Graph Frontend Surface Adapters And Inspector
• COE-535: Run Diff Symbol Navigation And Code Overlay
• COE-536: Cross Graph Code Memory And Work Chips
• COE-537: Code Graph Scale Accessibility And Parity Hardening
• COE-540: Canonical Codex Thread Reuse And Workspace Retention
• COE-541: Durable Codex Thread Archive And Debug Recovery
• COE-542: Target Branch Code Index And Revision Snapshots
• COE-543: Workspace Code Overlay And Composite Graph
• COE-544: Indexed Agent Code Context And Retrieval
• COE-545: Edge Delta And Module Topology Diff
• COE-546: Code Graph Bootstrap UX And End-To-End Validation
• COE-547: Central Multi-Repository Config And Safe Migration
• COE-548: Canonical Repository Binding And Task Propagation
• COE-549: Verified Checkouts Instructions And Harness Envelopes
• COE-550: Per-Instance Memory Catalog And Source Migration
• COE-551: Scoped Cross-Repository Memory And Leaf Overlays
• COE-553: Parent Execution Roots And Child Workspace Reuse
• COE-554: Restart-Safe Parent Integration Controller
• COE-555: Parent Repair Review And Merge Lifecycle
• COE-556: Bottom-Up Subtree Cleanup And Recovery
• COE-562: Implement artifact validation and digest primitives
• COE-563: Implement task-packet admission and freeze tooling
• COE-564: Implement verifier execution and outcome records
• COE-565: Implement isolated workspace materialization
• COE-566: Implement configurable run matrices and scheduling
• COE-567: Implement run lifecycle and process-protocol primitives
• COE-608: ACP Profiles And Executable Protocol Client
• COE-609: ACP Session Ownership And Durable Recovery
• COE-610: ACP Client Callbacks And Session Configuration
• COE-611: ACP Execution Routing And Worker Integration
• COE-612: ACP Operator Requests And Response Routing
• COE-613: ACP Extensions And Harness Operations
• COE-615: ACP Runtime Conformance And Live Qualification

Source refs

• COE-252
• COE-253
• COE-254
• COE-255
• COE-256
• COE-258
• COE-259
• COE-260
• COE-261
• COE-262
• COE-263
• COE-264
• COE-265
• COE-266
• COE-267
• COE-268
• COE-269
• COE-270
• COE-271
• COE-272
• COE-273
• COE-274
• COE-277
• COE-280
• COE-281
• COE-282
• COE-284
• COE-287
• COE-294
• COE-382
• COE-383
• COE-384
• COE-385
• COE-386
• COE-387
• COE-389
• COE-390
• COE-391
• COE-392
• COE-393
• COE-394
• COE-395
• COE-396
• COE-397
• COE-398
• COE-399
• COE-400
• COE-401
• COE-402
• COE-403
• COE-404
• COE-405
• COE-406
• COE-407
• COE-408
• COE-409
• COE-410
• COE-411
• COE-412
• COE-413
• COE-414
• COE-415
• COE-416
• COE-417
• COE-419
• COE-423
• COE-425
• COE-426
• COE-428
• COE-429
• COE-434
• COE-435
• COE-448
• COE-449
• COE-452
• COE-453
• COE-454
• COE-456
• COE-458
• COE-460
• COE-461
• COE-463
• COE-464
• COE-465
• COE-467
• COE-468
• COE-469
• COE-471
• COE-473
• COE-475
• COE-476
• COE-478
• COE-479
• COE-480
• COE-481
• COE-482
• COE-483
• COE-484
• COE-485
• COE-486
• COE-487
• COE-488
• COE-489
• COE-490
• COE-491
• COE-492
• COE-493
• COE-494
• COE-495
• COE-496
• COE-497
• COE-498
• COE-499
• COE-500
• COE-501
• COE-502
• COE-503
• COE-504
• COE-505
• COE-506
• COE-507
• COE-508
• COE-520
• COE-521
• COE-522
• COE-523
• COE-524
• COE-525
• COE-526
• COE-527
• COE-528
• COE-529
• COE-530
• COE-531
• COE-532
• COE-533
• COE-534
• COE-535
• COE-536
• COE-537
• COE-540
• COE-541
• COE-542
• COE-543
• COE-544
• COE-545
• COE-546
• COE-547
• COE-548
• COE-549
• COE-550
• COE-551
• COE-553
• COE-554
• COE-555
• COE-556
• COE-562
• COE-563
• COE-564
• COE-565
• COE-566
• COE-567
• COE-608
• COE-609
• COE-610
• COE-611
• COE-612
• COE-613
• COE-615