{"id":"fc377726-c57f-48ff-bbad-9dfb62504676","slug":"yottameta-yotta-logs","kind":"skill","name":"yotta-logs","summary":"元史 —— 跨智能体的历史会话 / 记忆日志检索技能：零依赖检索 / 分析 JSONL、JSON、SQLite、Markdown 多格式会话与记忆文件，回溯旧对话与父会话上下文，为跨会话追溯提供原始日志依据。触发：用户问起先前聊过的内容 / 父会话 / 历史上下文、要查以前说过的结论、跨会话回溯某次讨论、需要从会话日志或记忆文件定位某段决策时。边界：仅读取本机自己的会话日志 / 记忆文件；不修改、","owner":"YottaMeta","repoUrl":"https://github.com/YottaMeta/yotta-logs","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-08-26T16:24:25.000Z","addedAt":"2026-10-14T11:38:54.947Z","logoUrl":"https://avatars.githubusercontent.com/u/299793841?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["databases","files-documents"],"tags":["yottaskills"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T21:35:31.886Z","sample":false,"url":"https://conduits.dev/tools/yottameta-yotta-logs","language":"Python","transports":["stdio"],"install":{"npm":"@yottameta/yotta-logs"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"<p align=\"center\"><b>Language</b>: English · <a href=\"./README.zh-CN.md\">中文</a></p>\n\n<p align=\"center\">\n  <img src=\"assets/banner.png\" alt=\"yotta-logs banner\" width=\"100%\" />\n</p>\n\n<h1 align=\"center\">yotta-logs · 元史 (Yuanshi)</h1>\n\n<p align=\"center\">YottaMeta's skill for retrieving and analyzing <b>historical session / memory logs across AI agents</b>: zero-dependency search over JSONL, JSON, SQLite and Markdown records to recall past conversations and parent-session context with original-log evidence.</p>\n<p align=\"center\">Activates when the user references previous content / a parent session / historical context — <b>no jq / rg needed; pure standard-library deterministic retrieval</b>.</p>\n<p align=\"center\">Pure Python 3.8+ standard library, zero external dependencies; Windows + Linux + macOS; read-only local logs, redacted by default, never uploaded.</p>\n\n<p align=\"center\">\n  <a href=\"LICENSE\"><img alt=\"License: MIT\" src=\"https://img.shields.io/badge/license-MIT-blue\" /></a>\n  <a href=\"https://agentskills.io/\"><img alt=\"Standard: agentskills.io\" src=\"https://img.shields.io/badge/standard-agentskills.io-orange\" /></a>\n  <a href=\"https://www.npmjs.com/package/@yottameta/yotta-logs\"><img alt=\"npm package\" src=\"https://img.shields.io/npm/v/@yottameta/yotta-logs\" /></a>\n  <a href=\"https://github.com/YottaMeta/yotta-logs\"><img alt=\"GitHub stars\" src=\"https://img.shields.io/github/stars/YottaMeta/yotta-logs\" /></a>\n  <a href=\"https://github.com/YottaMeta/yotta-logs/commits/main\"><img alt=\"last commit\" src=\"https://img.shields.io/github/last-commit/YottaMeta/yotta-logs\" /></a>\n  <a href=\"https://github.com/YottaMeta/yotta-logs\"><img alt=\"PRs welcome\" src=\"https://img.shields.io/badge/PRs-welcome-brightgreen\" /></a>\n</p>\n\n## What it is\n\nAgents generate a steady stream of session and memory records (JSONL / single-file JSON / SQLite / Markdown…). When tracing across sessions, the hard part is rarely \"remembering that something happened\" — it is finding *where the original text is, who said it, and when*. Yuanshi turns those records into a **deterministic retrieval engine**: discover every log and memory source → search by keyword / regex / date / session / role / source / kind / format → extract raw conversation → summarize messages, tokens, cost and tool usage.\n\nIt is not tied to any single platform: it is an agent-agnostic toolkit that works in any agent supporting Agent Skills. Zero dependencies, read-only local access, no network; output is redacted by default so secrets and tokens in logs never leak into context.\n\n## Core value\n\n- **Zero-dependency retrieval** — Python 3.8+ standard library; no jq / rg / ripgrep; works out of the box on Windows + Linux + macOS.\n- **Multi-format (v0.2.0)** — not JSONL-only anymore: JSONL / single-file JSON / SQLite (opencode, Cursor state.vscdb…) / Markdown (memory + free notes) / binary (title-only) via \"format family × field-alias normalization + config fallback\", on a unified Record model.\n- **Full source discovery** — `locate` / discover finds common local log and memory sources (Codex / Claude Code / Clawdbot / opencode / Gemini / yotta-memory / Codex notes…), filtered by the default search scope.\n- **Fault-tolerant parsing** — bad lines and fields are skipped and counted, never aborting a search; binary / encrypted files degrade to titles.\n- **Redacted by default** — output masks likely secrets / tokens / credentials (sk-, ghp_, AKIA, JWT, Bearer, URL passwords, key=value assignments, over-long tokens); disable with --no-redact.\n- **Multi-dimensional filtering** — keyword (case-insensitive) / regex / date / session ID / sessions.json alias / role (user / assistant / tool / system / developer) / source (--source) / kind (--kind) / format (--format).\n- **Structured output** — --json emits clean JSON with source, session ID, line number, timestamp and role, ideal for programmatic provenance checks.\n- **Read-only & safe** — reads local logs and memory files only; never modifies, deletes or uploads; complements yotta-memory (semantic memory).\n\n## Why use it\n\n| Advantage | Description |\n|---|---|\n| **Zero dependency** | Python 3.8+ standard library; no model, database or external service; Windows + Linux + macOS |\n| **Multi-format** | JSONL / JSON / SQLite / Markdown / binary; field-alias normalization + config fallback |\n| **Deterministic** | Reproducible, explainable logic; hits return original fragments + line numbers, no model guessing |\n| **Redacted by default** | Likely secrets / tokens / credentials masked automatically |\n| **Default scope** | Session + structured memory sources on by default; free notes / binary logs off unless explicitly enabled |\n| **Fault-tolerant** | Tolerates storage differences across agents; bad lines skipped without aborting; encrypted files fall back to titles |\n| **Pinpoint provenance** | Hits carry source / session ID / line / timestamp / role for exact tracing |\n| **Ecosystem distribution** | GitHub + npm + ClawHub synced; four install methods (npx / git clone / Download ZIP / install.sh) |\n\n## Commands\n\n| Command | Description |\n|---|---|\n| locate | Discover all local log / memory sources (source / format / kind / default on-off) |\n| scan | List all sessions across sources (source / session ID / date / message count / size / alias) |\n| search | Cross-source search: keyword / regex + date / session / role / source / kind / format filters; timeline hits (--json structured) |\n| session | Extract one session's raw text (timeline + role + text); --role filter, --tools annotate tool calls |\n| stats | Session statistics: messages / role distribution / token / cost / time range / per-source (--daily daily rollup) |\n| tools | Tool-call frequency ranking |\n| version | Print version |\n\n## Quick start\n\nOn Windows use `python`; on Linux/macOS use `python3`.\n\n```bash\n# Discover all local log / memory sources\npython3 scripts/yotta_logs.py locate\n\n# Cross-source keyword search (default scope = session + structured memory; free notes off)\npython3 scripts/yotta_logs.py search \"deployment plan\"\n\n# Target a directory / file (format family auto-sniffed)\npython3 scripts/yotta_logs.py scan --dir ~/.clawdbot/agents/<agentId>/sessions\n\n# Regex + date + session filters\npython3 scripts/yotta_logs.py search \"CI failed\" --regex --date 2026-08-26 --dir /path/to/sessions\n\n# Filter by source / kind / format (source names from locate)\npython3 scripts/yotta_logs.py search \"remember\" --kind memory\npython3 scripts/yotta_logs.py search \"XSS\" --source opencode-db\npython3 scripts/yotta_logs.py search \"deploy\" --format sqlite\n\n# Explicitly enable free notes (off by default)\npython3 scripts/yotta_logs.py search \"push gate\" --kind note\n\n# Extract a single session's raw text\npython3 scripts/yotta_logs.py session abc123 --dir /path/to/sessions\n\n# Statistics (messages / tokens / cost / daily rollup)\npython3 scripts/yotta_logs.py stats --dir /path/to/sessions --daily\n\n# Tool-call ranking\npython3 scripts/yotta_logs.py tools --dir /path/to/sessions\n\n# JSON structured output (for programmatic checks)\npython3 scripts/yotta_logs.py search \"deployment plan\" --dir /path/to/sessions --json\n```\n\nExit codes (consistent with the YottaMeta family): 0 = success; 1 = no match / empty result; 4 = usage error / fatal exception.\n\nWhen --dir is omitted, the engine tries $YOTTA_LOGS_DIR, then full source discovery (locate logic) filtered by the default scope; if nothing is found it exits 4 with a hint.\n\n## Installation\n\nPick any of the four methods below; the order is the recommended priority. Skill files always come from **npm** (GitHub can be slow without a proxy; npm supports mirrors).\n\n### Method 1: npm one-liner (recommended)\n\n```text\n# Optional China mirror: npm config set registry https://registry.npmmirror.com\nnpx -y @yottameta/yotta-logs@0.3.3 --agent <agent-name>      # install to the agent's default user-level skills dir\nnpx -y @yottameta/yotta-logs@0.3.3 --dir <your-skills-dir>   # point to the skills dir itself (e.g. ~/.codex/skills)\n```\n\n- `--agent <name>` installs to that agent's default user-level directory; `--list` shows each agent's default directory.\n- `--dir <path>` installs to the given directory; for agents not in the preset list, point `--dir` at their skills directory.\n- If the mirror has not synced the new package (404): add `--registry=https://registry.npmjs.org/` (a proxy may be needed in China), or wait for the mirror cache.\n\n### Method 2: git clone (developers / git available)\n\n```text\ngit clone https://github.com/YottaMeta/yotta-logs.git <your-skills-dir>/yotta-logs\n```\n\n### Method 3: GitHub Download ZIP (manual / no git)\n\nOn the GitHub repository `YottaMeta/yotta-logs`, click **Code → Download ZIP**, unzip it and put the `yotta-logs` folder into the agent's skills directory.\n\n### Method 4: install.sh (multi-agent one-liner script)\n\n```text\nbash install.sh --agent <name>   # install to the agent's default user-level directory\nbash install.sh --dir <path>     # install to the given directory\nbash install.sh --list           # list agents -> default directories\n```\n\n> Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use GitHub and may fail without a proxy in China.\n## Usage with an AI agent\n\n1. Wire this repo's SKILL.md into any agent's skills / rules system (see Installation above).\n2. When the user asks \"what was that deployment plan we discussed?\", locate and search:\n   ```bash\n   python3 scripts/yotta_logs.py locate\n   python3 scripts/yotta_logs.py search \"deployment plan\"\n   ```\n   You get a timeline of hits (source / session / time / role / raw fragment).\n3. For full context, extract the session:\n   ```bash\n   python3 scripts/yotta_logs.py session <sessionId> --dir <logs directory>\n   ```\n4. For exact provenance, use --json to get source / session ID / line number / timestamp and cite it in your answer.\n5. To review a session's cost or tool-use distribution, use stats / tools.\n\n## Development & validation\n\n- Tests: `python scripts/test_yotta_logs.py` (139 cases: 75 v0.1.0 regression + 64 v0.2.0 generalization)\n- Basic validation: `python tools/validate-skill.py yotta-logs` (run from the repository root)\n- Format registry: references/agent-formats.md; unified format: references/format.md; CLI protocol: references/cli.md; security boundary: references/security.md\n\n## Changelog\n\n- v0.3.1 (2026-09-13): Removed machine-specific hardcoded paths; discovery and config now follow environment variables and platform defaults, with regression coverage.\n- v0.3.0 (2026-09-08): Evaluation-driven refinement — added FAQ, hardened installer error handling and exit codes, and added installer tests.\n\n- v0.2.2 (2026-08-29): Install docs alignment — unified four install methods (npx -y @yottameta/yotta-logs@0.3.3 --agent/--dir, git clone, GitHub Download ZIP, install.sh --agent/--dir/--list), removed the legacy GitHub-clone installer and global-install (-g) recommendations; bilingual README install section synced to 发布规范 §3.3.1. No functional change.\n\n- v0.2.1 (2026-08-27): Bilingual documentation — English README as the GitHub / npm / ClawHub homepage, full Chinese doc moved to README.zh-CN.md, English npm description.\n- v0.2.0 (2026-08-27): Multi-format generalization — JSONL / single-file JSON / SQLite (opencode etc.) / Markdown (memory + free notes) / binary; unified Record + field-alias normalization + config fallback; discover; new --source / --kind / --format filters and default search scope (session + structured memory on, free notes / binary logs off). See CHANGELOG.md.\n- v0.1.0 (2026-08-27): Initial release — zero-dependency JSONL session log search engine (locate / scan / search / session / stats / tools / version + default redaction + sessions.json alias + read-only).\n\n## References\n\n- references/faq.md\n\n## License\n\nMIT © YottaMeta — see [LICENSE](./LICENSE).\n"}