✨ feat(app): add ingest-imports CLI command for batch JSONL ingestion

- Add `codex-mem ingest-imports` command to import watcher/relay note
  events through newline-delimited JSONL input
- Add operator-facing import-ingestion.md guide documenting JSONL
  schema, example invocations, and output shape
- Update normative spec with `memory_save_import` and
  `memory_save_imported_note` tool contracts plus example payloads
- Add app-level test coverage for text and JSON output formats
- Update README and docs index links to reference new ingestion guide

Author: cocosip

README.md

@@ -10,6 +10,7 @@ It stores structured notes and handoffs in SQLite, restores continuity across re
 - `serve-http` runs a native MCP HTTP server for remote or private deployment.
 - `doctor` reports config, database readiness, migration status, provenance coverage, and MCP tool availability.
 - AGENTS template installation is implemented for global and project workflows.
+- one-shot watcher/relay batch ingestion is available through `ingest-imports`.
 
 Normative product docs live in [docs/spec/README.md](docs/spec/README.md).
 Go implementation docs now live under [docs/go/README.md](docs/go/README.md), grouped into user, operator, and maintainer directories.
@@ -22,6 +23,8 @@ Use the docs by audience:
   How memory works, what gets saved, and prompt patterns for normal Codex usage.
 - [Operator docs](docs/go/operator/README.md)
   Client registration, deployment/readiness, packaging, and troubleshooting.
+- [Import ingestion guide](docs/go/operator/import-ingestion.md)
+  JSONL batch ingestion for watcher and relay artifacts through `ingest-imports`.
 - [Maintainer docs](docs/go/maintainer/README.md)
   Source-tree MCP integration, implementation planning, and development tracking.
 
@@ -73,6 +76,8 @@ They are not MCP tools and are not the normal end-user interaction path.
   Prints effective config plus runtime readiness and audit diagnostics.
 - `codex-mem doctor --json`
   Prints the same diagnostics in machine-readable JSON for automation or CI checks.
+- `codex-mem ingest-imports --source watcher_import [--input events.jsonl] [--json]`
+  Imports newline-delimited watcher or relay note events into durable imported notes plus audit records.
 - `codex-mem migrate`
   Opens the configured SQLite database and applies embedded migrations.
 - `codex-mem serve`
@@ -113,6 +118,7 @@ The current MCP server exposes:
 Request and response examples are documented in [example-payloads.md](docs/spec/appendices/example-payloads.md).
 For concrete packaged-binary client setup examples, use [client-examples.md](docs/go/operator/client-examples.md).
 For maintainer-oriented MCP transport and smoke-test guidance from the source tree, use [mcp-integration.md](docs/go/maintainer/mcp-integration.md).
+For operator-facing JSONL batch ingestion details, use [import-ingestion.md](docs/go/operator/import-ingestion.md).
 For a quick explanation of how memory works, what gets saved, and when scope matters, use [how-memory-works.md](docs/go/user/how-memory-works.md).
 For end-user prompt templates that cause Codex to pick the memory tools automatically, use [prompt-examples.md](docs/go/user/prompt-examples.md).
 For release packaging and operator guidance, use [release-readiness.md](docs/go/operator/release-readiness.md).

docs/go/README.md

@@ -23,6 +23,7 @@ If you are using `codex-mem` day to day:
 If you are deploying or operating the MCP server:
 
 - [Client Examples](./operator/client-examples.md)
+- [Import Ingestion](./operator/import-ingestion.md)
 - [Release Readiness](./operator/release-readiness.md)
 - [Troubleshooting](./operator/troubleshooting.md)
 

docs/go/maintainer/development-tracker.md

@@ -301,6 +301,19 @@ Current blockers:
 - In progress: none.
 - Blockers: none.
 - Next step: decide whether to keep polishing the import workflow through spec-facing docs and watcher/relay integration, or move on to a different product-facing slice.
+### 2026-03-16 Session Update
+
+- Completed: Added a real CLI-side caller for the imported-note workflow with `codex-mem ingest-imports`. The command resolves scope, starts one ingestion session, reads newline-delimited JSON import events from stdin or `--input`, and routes each event through `memory_save_imported_note` semantics so watcher/relay batches can create imported notes plus audit records without going through MCP. Added app-level coverage for text/JSON summaries and persisted note/import counts.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether to keep this CLI batch path as the main watcher/relay bridge for now, or add a more direct integration path on top of the same imported-note service.
+### 2026-03-16 Session Update
+
+- Completed: Updated the normative spec to include `memory_save_import` and `memory_save_imported_note` tool contracts plus example request/response payloads, and added an operator-facing [import-ingestion.md](../operator/import-ingestion.md) guide that documents the `ingest-imports` JSONL schema, example invocations, output shape, and current fail-fast batch semantics.
+- In progress: none.
+- Blockers: none.
+- Next step: decide whether `ingest-imports` should remain the main watcher/relay bridge for now or whether a more direct long-lived integration path is worth adding later.
+
 ## Recommended Next Step
 
 Recommended next implementation slice:

docs/go/operator/README.md

@@ -6,6 +6,8 @@ Start here:
 
 - [Client Examples](./client-examples.md)
   Real MCP client registration examples for local stdio and remote HTTP.
+- [Import Ingestion](./import-ingestion.md)
+  JSONL batch ingestion for watcher or relay artifacts through `ingest-imports`.
 - [Release Readiness](./release-readiness.md)
   Packaging, readiness, and release checklist.
 - [Troubleshooting](./troubleshooting.md)

docs/go/operator/import-ingestion.md

@@ -0,0 +1,125 @@
+# Go Import Ingestion
+
+## Purpose
+
+This document explains how operators can use `codex-mem ingest-imports` to turn watcher or relay batches into durable imported notes plus import audit records.
+
+Audience:
+
+- operators wiring watcher or relay output into `codex-mem`
+- maintainers validating packaged-binary ingestion behavior
+
+Use this when:
+
+- you need a one-shot batch bridge into the imported-note workflow
+- your upstream process can emit newline-delimited JSON events
+
+Do not use this for:
+
+- normal day-to-day Codex prompting
+- direct MCP tool calls from a client
+
+## Command Shape
+
+Minimal stdin example:
+
+```powershell
+Get-Content .\events.jsonl | codex-mem.exe ingest-imports --source watcher_import
+```
+
+Read from a file and print JSON:
+
+```powershell
+codex-mem.exe ingest-imports --source relay_import --input .\relay-events.jsonl --json
+```
+
+Useful flags:
+
+- `--source watcher_import|relay_import`
+  Required. Declares the provenance source for every event in the batch.
+- `--input <path>`
+  Optional. Reads JSONL from a file instead of stdin.
+- `--cwd <path>`
+  Optional. Resolves scope from a specific workspace root.
+- `--branch-name <name>`
+  Optional. Carries branch metadata into the ingestion session.
+- `--repo-remote <url>`
+  Optional. Strengthens scope resolution with the repository remote.
+- `--task <text>`
+  Optional. Overrides the default ingestion session task summary.
+- `--json`
+  Optional. Prints a structured report instead of line-oriented text output.
+
+## Event Schema
+
+Each non-empty line must be one JSON object.
+
+Required fields:
+
+- `type`
+  Canonical note type: `decision`, `bugfix`, `discovery`, `constraint`, `preference`, or `todo`.
+- `title`
+  Short imported note title.
+- `content`
+  Durable imported note body.
+- `importance`
+  Integer importance from `1` to `5`.
+
+At least one of:
+
+- `external_id`
+  Stable upstream artifact id used for import dedupe.
+- `payload_hash`
+  Stable content hash used when no external id exists.
+
+Optional fields:
+
+- `tags`
+  String array of note tags.
+- `file_paths`
+  String array of touched or relevant paths.
+- `related_project_ids`
+  String array of related project ids for cross-project retrieval links.
+- `status`
+  Note lifecycle state. Defaults to `active` when omitted.
+- `privacy_intent`
+  When set to `private`, `do_not_store`, or `ephemeral_only`, the import is audited but note materialization is suppressed.
+
+## Example JSONL
+
+```jsonl
+{"external_id":"watcher:1","type":"discovery","title":"Imported discovery","content":"Useful watcher discovery.","importance":4,"tags":["watcher"]}
+{"external_id":"watcher:2","type":"todo","title":"Private follow-up","content":"Should stay audit-only.","importance":3,"privacy_intent":"private"}
+```
+
+Behavior to expect from this batch:
+
+- the first event creates an imported durable note plus an import audit record
+- the second event creates only a suppressed import audit record
+
+## Output Semantics
+
+Text mode prints a compact summary such as:
+
+```text
+ingest imports ok
+source=watcher_import
+input=stdin
+session_id=sess_20260316_001
+resolved_by=repo_remote
+processed=2
+materialized=1
+suppressed=1
+note_deduplicated=0
+import_deduplicated=0
+warnings=1
+```
+
+JSON mode returns the same summary plus per-line results, including the created or reused `note_id` and `import_id`.
+
+## Operational Notes
+
+- `ingest-imports` starts one fresh session for the whole batch after resolving scope.
+- Each event uses the same imported-note workflow as `memory_save_imported_note`.
+- Existing explicit memory wins over weaker imported duplicates in the same project.
+- The current implementation is fail-fast: the first invalid line stops the batch and returns an error.

docs/spec/appendices/example-payloads.md

@@ -252,6 +252,124 @@ These examples illustrate intent and semantics. They are not tied to one impleme
 }
 ```
 
+## `memory_save_import`
+
+### Example request
+
+```json
+{
+  "scope": {
+    "system_id": "sys_order_platform",
+    "project_id": "proj_order_web",
+    "workspace_id": "ws_order_web_main"
+  },
+  "session_id": "sess_20260313_001",
+  "source": "watcher_import",
+  "external_id": "watcher:event:392",
+  "payload_hash": "sha256:4db5b7c6f2a9",
+  "privacy_intent": ""
+}
+```
+
+### Example response
+
+```json
+{
+  "ok": true,
+  "data": {
+    "import": {
+      "import_id": "import_701",
+      "scope": {
+        "system_id": "sys_order_platform",
+        "project_id": "proj_order_web",
+        "workspace_id": "ws_order_web_main"
+      },
+      "session_id": "sess_20260313_001",
+      "source": "watcher_import",
+      "external_id": "watcher:event:392",
+      "payload_hash": "sha256:4db5b7c6f2a9",
+      "suppressed": false,
+      "imported_at": "2026-03-13T11:18:00Z"
+    },
+    "stored_at": "2026-03-13T11:18:00Z",
+    "suppressed": false,
+    "deduplicated": false
+  },
+  "warnings": []
+}
+```
+
+## `memory_save_imported_note`
+
+### Example request
+
+```json
+{
+  "scope": {
+    "system_id": "sys_order_platform",
+    "project_id": "proj_order_web",
+    "workspace_id": "ws_order_web_main"
+  },
+  "session_id": "sess_20260313_001",
+  "source": "watcher_import",
+  "external_id": "watcher:event:393",
+  "payload_hash": "sha256:b7f650bfe12c",
+  "type": "discovery",
+  "title": "Watcher captured checkout retry regression",
+  "content": "A local watcher run showed the checkout retry button still posts a legacy payment alias after draft restore.",
+  "importance": 4,
+  "tags": ["watcher", "checkout", "validation"],
+  "file_paths": ["src/order/checkout.ts"],
+  "status": "active"
+}
+```
+
+### Example response
+
+```json
+{
+  "ok": true,
+  "data": {
+    "note": {
+      "note_id": "note_488",
+      "scope": {
+        "system_id": "sys_order_platform",
+        "project_id": "proj_order_web",
+        "workspace_id": "ws_order_web_main"
+      },
+      "session_id": "sess_20260313_001",
+      "type": "discovery",
+      "title": "Watcher captured checkout retry regression",
+      "content": "A local watcher run showed the checkout retry button still posts a legacy payment alias after draft restore.",
+      "importance": 4,
+      "status": "active",
+      "source": "watcher_import",
+      "created_at": "2026-03-13T11:24:00Z"
+    },
+    "import": {
+      "import_id": "import_702",
+      "scope": {
+        "system_id": "sys_order_platform",
+        "project_id": "proj_order_web",
+        "workspace_id": "ws_order_web_main"
+      },
+      "session_id": "sess_20260313_001",
+      "source": "watcher_import",
+      "external_id": "watcher:event:393",
+      "payload_hash": "sha256:b7f650bfe12c",
+      "durable_memory_id": "note_488",
+      "suppressed": false,
+      "imported_at": "2026-03-13T11:24:00Z"
+    },
+    "materialized": true,
+    "note_deduplicated": false,
+    "import_deduplicated": false,
+    "suppressed": false
+  },
+  "warnings": []
+}
+```
+
 ## `memory_search`
 
 ### Example request