Add easy-memory skill

.gitignore

@@ -4,3 +4,9 @@
 # Python bytecode files
 __pycache__/
 *.pyc
+
+# Project-local easy-memory logs
+/easy-memory/
+
+# Runtime-generated logs inside the experimental easy-memory skill
+skills/.experimental/easy-memory/logs/

skills/.experimental/easy-memory/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 memeda230606@gmail.com
+
+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.

skills/.experimental/easy-memory/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Easy Memory"
+  short_description: "Project-local memory logs with optional agent preprocessing"
+  default_prompt: "Use $easy-memory to read, search, and maintain project-local memory logs for the current project."
+
+policy:
+  allow_implicit_invocation: true

skills/.experimental/easy-memory/assets/examples/agent-config.example.json

@@ -0,0 +1,9 @@
+{
+  "enabled": true,
+  "api_style": "codex_exec",
+  "model": "gpt-5.3-codex-spark",
+  "codex_service_tier": "fast",
+  "codex_reasoning_effort": "medium",
+  "timeout_seconds": 120,
+  "system_prompt_file": "./easy-memory/custom-memory-agent-prompt.md"
+}

skills/.experimental/easy-memory/assets/examples/request.example.json

@@ -0,0 +1,57 @@
+{
+  "schema_version": "easy_memory_agent_request_v2",
+  "mode": "search_memory",
+  "task_context": "用户正在排查当前项目中的记忆管理 agent 配置问题，需要找出与配置加载和路径返回相关的历史记忆。",
+  "cwd": "/Users/example/workspace/project-a",
+  "log_dir": "/Users/example/workspace/project-a/easy-memory",
+  "keywords": [
+    "memory-agent",
+    "config",
+    "path"
+  ],
+  "max_results": 5,
+  "entries": [
+    {
+      "entry_id": "entry-001",
+      "log_file": "2026-03-13.log",
+      "ref_level": "high",
+      "factual": true,
+      "content": "Added project-local related-resource metadata support and required task-context for read/search flows.",
+      "timestamp": "2026-03-13:16:00",
+      "paths": [
+        {
+          "path_id": "path-001",
+          "resource_type": "local_path",
+          "path": "src/memory_agent_config.py",
+          "directory": "src",
+          "path_format": "project_relative"
+        },
+        {
+          "path_id": "path-002",
+          "resource_type": "local_path",
+          "path": "/opt/shared/docs/memory-agent.md",
+          "directory": "/opt/shared/docs",
+          "path_format": "absolute",
+          "system_hint": "Darwin arm64 @example-host"
+        },
+        {
+          "path_id": "path-003",
+          "resource_type": "url",
+          "path": "https://example.com/docs/easy-memory",
+          "directory": "https://example.com/docs"
+        }
+      ],
+      "rendered_block": "2026-03-13.log: [ID:entry-001] [REF:high] [FACT:true] Added project-local related-resource metadata support and required task-context for read/search flows. [PATHS:[{\"id\":\"path-001\",\"path\":\"src/memory_agent_config.py\",\"directory\":\"src\",\"resource_type\":\"local_path\",\"path_format\":\"project_relative\"},{\"id\":\"path-002\",\"path\":\"/opt/shared/docs/memory-agent.md\",\"directory\":\"/opt/shared/docs\",\"resource_type\":\"local_path\",\"path_format\":\"absolute\",\"system_hint\":\"Darwin arm64 @example-host\"},{\"id\":\"path-003\",\"path\":\"https://example.com/docs/easy-memory\",\"directory\":\"https://example.com/docs\",\"resource_type\":\"url\"}]] [TIME:2026-03-13:16:00]\n  Related resource ID path-001 [local_path, project_relative]: src/memory_agent_config.py (container: src)\n  Related resource ID path-002 [local_path, absolute]: /opt/shared/docs/memory-agent.md (container: /opt/shared/docs; system: Darwin arm64 @example-host)\n  Related resource ID path-003 [url]: https://example.com/docs/easy-memory (container: https://example.com/docs)"
+    },
+    {
+      "entry_id": "entry-002",
+      "log_file": "2026-03-12.log",
+      "ref_level": "medium",
+      "factual": true,
+      "content": "Legacy entry without stored related-resource metadata remains compatible with read/search output.",
+      "timestamp": "2026-03-12:11:20",
+      "paths": [],
+      "rendered_block": "2026-03-12.log: [ID:entry-002] [REF:medium] [FACT:true] Legacy entry without stored related-resource metadata remains compatible with read/search output. [TIME:2026-03-12:11:20]"
+    }
+  ]
+}

skills/.experimental/easy-memory/assets/examples/response.example.txt

@@ -0,0 +1,6 @@
+2026-03-13.log: [ID:entry-001] [REF:high] [FACT:true] Added project-local related-resource metadata support and required task-context for read/search flows. [PATHS:[{"id":"path-001","path":"src/memory_agent_config.py","directory":"src","resource_type":"local_path","path_format":"project_relative"},{"id":"path-002","path":"/opt/shared/docs/memory-agent.md","directory":"/opt/shared/docs","resource_type":"local_path","path_format":"absolute","system_hint":"Darwin arm64 @example-host"},{"id":"path-003","path":"https://example.com/docs/easy-memory","directory":"https://example.com/docs","resource_type":"url"}]] [TIME:2026-03-13:16:00]
+  Related resource ID path-001 [local_path, project_relative]: src/memory_agent_config.py (container: src)
+  Related resource ID path-002 [local_path, absolute]: /opt/shared/docs/memory-agent.md (container: /opt/shared/docs; system: Darwin arm64 @example-host)
+  Related resource ID path-003 [url]: https://example.com/docs/easy-memory (container: https://example.com/docs)
+
+[SUMMARY] 过滤无关记忆后，仅保留与 memory-agent 配置和相关资源返回有关的结果。

skills/.experimental/easy-memory/assets/examples/script-output.example.txt

@@ -0,0 +1,6 @@
+2026-03-13.log: [ID:entry-001] [REF:high] [FACT:true] Added stable plain-text filtering output for memory-agent responses. [PATHS:[{"id":"path-001","path":"skills/.experimental/easy-memory/scripts/memory_agent_client.py","directory":"skills/.experimental/easy-memory/scripts","resource_type":"local_path","path_format":"project_relative"},{"id":"path-002","path":"/opt/shared/docs/memory-agent.md","directory":"/opt/shared/docs","resource_type":"local_path","path_format":"absolute","system_hint":"Darwin arm64 @example-host"},{"id":"path-003","path":"https://example.com/docs/memory-agent","directory":"https://example.com/docs","resource_type":"url"}]] [TIME:2026-03-13:16:40]
+  Related resource ID path-001 [local_path, project_relative]: skills/.experimental/easy-memory/scripts/memory_agent_client.py (container: skills/.experimental/easy-memory/scripts)
+  Related resource ID path-002 [local_path, absolute]: /opt/shared/docs/memory-agent.md (container: /opt/shared/docs; system: Darwin arm64 @example-host)
+  Related resource ID path-003 [url]: https://example.com/docs/memory-agent (container: https://example.com/docs)
+
+[SUMMARY] 已移除无关内容，仅保留与当前记忆 agent 输出行为有关的完整记忆。

skills/.experimental/easy-memory/references/compatibility-notes.md

@@ -0,0 +1,89 @@
+# Compatibility Notes
+
+This document consolidates the naming-compatibility rules for `easy-memory`
+related-resource metadata.
+
+## Purpose
+
+`easy-memory` originally stored only local filesystem paths.
+Later revisions expanded the same metadata channel so it can also store:
+- project-relative local filesystem paths for resources inside the current
+  working directory
+- absolute local filesystem paths for resources outside the current working
+  directory
+- URLs
+- document addresses
+
+For backward compatibility, the historical field names and CLI option names were
+kept stable even though their meaning is now broader.
+
+## Historical Names And Current Meaning
+
+- `PATHS`
+  - Historical on-disk log field name
+  - Current meaning: array of related resource objects
+- `path_id`
+  - Historical object field name
+  - Current meaning: unique related resource ID
+- `path_ids`
+  - Historical agent-response field name from the older structured-response contract
+  - Current meaning when encountered: list of related resource IDs
+- `--related-path`
+  - Historical CLI option name
+  - Current meaning: project-local path, external absolute path, or
+    URL/document address
+- `--path-update`
+  - Historical CLI option name
+  - Current meaning: replace one related resource by ID
+- `--path-clear`
+  - Historical CLI option name
+  - Current meaning: clear one related resource by ID while preserving the ID
+
+## Stable Compatibility Rules
+
+- Existing logs that use `PATHS` remain valid.
+- Existing payloads that use `path_id` and older structured responses that use
+  `path_ids` remain valid.
+- Existing automation or tooling that calls `--related-path`, `--path-update`, or
+  `--path-clear` does not need renaming.
+- New implementations should interpret these historical names using the broader
+  related-resource meaning.
+- Older local-path entries that stored absolute paths remain valid and should be
+  interpreted as `path_format:"absolute"` when no explicit `path_format` is
+  present.
+
+## Resource Interpretation
+
+Each related resource object should be interpreted using `resource_type`:
+- `local_path`
+  - `path_format:"project_relative"` means `path` is relative to the current
+    working directory and `directory` is the corresponding relative container
+  - `path_format:"absolute"` means `path` is an absolute local filesystem path
+    and `directory` is the absolute parent directory, or the directory itself
+    if the stored target is already a directory
+  - `system_hint` may be present for `path_format:"absolute"` entries to record
+    a brief host hint for cross-machine work
+- `url`
+  - `path` is the URL or document address
+  - `directory` is the derived parent or container URL
+
+If older metadata does not include `resource_type`, the runtime should infer it.
+If older local-path metadata does not include `path_format`, the runtime should
+infer `absolute` for absolute-looking local paths and `project_relative` for
+relative-looking local paths.
+
+## Reading Strategy
+
+When reading `easy-memory` metadata:
+- do not assume `path` means a local filesystem path
+- treat `path_id` as a stable related resource identifier
+- use `resource_type` to decide whether the target is local or remote
+
+## Source Of Truth
+
+This note explains naming compatibility only.
+The canonical structural contracts remain:
+- `SKILL.md`
+- `references/openai-compatible-api.md`
+- `references/response-schema.md`
+- `references/script-output-schema.md`

skills/.experimental/easy-memory/references/installer-environments.md

@@ -0,0 +1,88 @@
+# Installer Environment Adapters
+
+This reference defines how automated installers may adapt `easy-memory` to different host environments while keeping the canonical skill package compatible with the upstream `openai/skills` repository.
+
+## Canonical Source Of Truth
+
+The tracked skill package must keep the upstream OpenAI skill structure as its source of truth:
+
+```text
+easy-memory/
+├── SKILL.md
+├── agents/
+│   └── openai.yaml
+├── scripts/
+├── references/
+└── assets/
+```
+
+The canonical source tree must not require host-specific directories such as Codex-only or Claude Code-only layout additions in order to be considered valid.
+
+## What Installers May Do
+
+An automated installer may inspect the target environment and generate local adapter artifacts for that environment. Examples include:
+- creating host-specific wrapper files that point back to the canonical skill contents,
+- translating the canonical system prompt or metadata into a host-specific agent definition,
+- wiring command entry points or local registration files required by the host,
+- prompting the user to provide local runtime configuration such as API base URL, model ID, API key, and agent enablement flags.
+- creating or updating a local project-scoped config file such as `./easy-memory/agent-config.json`.
+
+These installer-generated artifacts must be treated as local derived files, not as canonical source files for the upstream skill package.
+
+## What Installers Must Not Do
+
+Installers must not:
+- require the upstream package to commit host-specific adapter directories as part of the canonical source tree,
+- store user secrets or machine-specific credentials in tracked repository files,
+- rewrite core memory semantics in `scripts/` without the user explicitly choosing a different runtime mode,
+- make Codex, Claude Code, or any other environment-specific adapter the only supported execution path.
+
+## Configuration Placement
+
+For future memory-management agent support, use this split:
+- Canonical source package:
+  - `SKILL.md` for workflow rules,
+  - `agents/openai.yaml` for Codex/OpenAI UI metadata,
+  - `references/` for API contracts, prompt sources, and response schema documentation,
+  - `assets/` for sample request/response fixtures and templates,
+  - `scripts/` for deterministic execution logic.
+- Local installer or user environment:
+- API key,
+- local config file path,
+- base URL,
+- selected model ID,
+  - environment-specific enablement toggles,
+  - generated host adapter files.
+
+## Host Mapping Guidance
+
+If the installer targets Codex:
+- keep `agents/openai.yaml` as the canonical metadata file inside the skill package,
+- avoid inventing additional required Codex-only directories beyond the upstream package layout unless the host explicitly requires local generated artifacts.
+- prefer a generated local config that uses `api_style: "codex_exec"` instead of adding an HTTP provider by default.
+- when generating a default Codex local config, prefer:
+  - `model: "gpt-5.3-codex-spark"`
+  - `codex_service_tier: "fast"`
+  - `codex_reasoning_effort: "medium"`
+  - no API key or base URL fields unless the user explicitly selects an external provider.
+
+If the installer targets Claude Code:
+- prefer generating local adapter artifacts from the canonical prompt and metadata sources rather than making Claude-specific files the source of truth,
+- keep generated Claude-oriented files installer-managed and replaceable.
+
+If the installer targets another host:
+- map from the canonical package into that host's local registration mechanism,
+- keep the mapping reversible and avoid embedding secrets into the installed skill package.
+
+## Recommended Local Config File
+
+For project-scoped installation flows, prefer a local config file at:
+- `./easy-memory/agent-config.json`
+
+The installer may populate this file with non-secret defaults and prompt the user for secret values or defer those to environment variables.
+
+Environment variables should override the local config file so that host-specific launchers can supply temporary or machine-specific values without rewriting project-local state.
+
+## Packaging Rule
+
+If a skill is intended for one-click installation from GitHub or another installer-supported source, the repository copy should remain self-contained and portable without requiring post-clone source edits. Environment-specific supplementation should happen as a local install step, not as a divergence from the upstream-compatible source package.

skills/.experimental/easy-memory/references/memory-agent-system-prompt.md

@@ -0,0 +1,40 @@
+# Memory-Agent System Prompt
+
+Use this file as the canonical prompt source for the `easy-memory`
+memory-management preprocessing agent.
+
+## Canonical Prompt
+
+```text
+You are the easy-memory preprocessing agent.
+
+Your only job is to remove memory content that is unrelated to the current
+task and keep only the memories that remain relevant.
+
+Rules:
+1. Treat the provided memory logs as source material, not as something you can
+   rewrite or reinterpret.
+2. Use the provided task_context to decide relevance.
+3. Delete or ignore every memory block that is not relevant to the current
+   task.
+4. For every memory block that remains relevant, return it in its complete
+   original format exactly as provided.
+5. Do not rewrite IDs, timestamps, related-resource lines, URLs, file paths, or
+   log-file prefixes.
+6. Do not return JSON, Markdown lists, explanations, or extra commentary.
+7. After the retained memory blocks, append exactly one final summary line that
+   starts with `[SUMMARY]`.
+8. Keep the summary concise and no longer than 500 characters.
+9. If no memory remains relevant after filtering, return only the `[SUMMARY]`
+   line.
+10. The summary must reflect only the retained task-relevant memories.
+```
+
+## Usage Notes
+
+- Installers may translate this canonical prompt into host-specific adapter
+  files.
+- The canonical source of truth remains this file, not any generated host
+  adapter.
+- Local overrides may exist in user environment configuration, but
+  repository-tracked defaults should derive from this prompt.