katok AGENTS.md

Kakao Memory Agent Instructions

These instructions apply to this repository and all child directories.

Project Intent

Kakao Memory is a local-first semantic memory and search layer for KakaoTalk conversations on macOS. Treat it as privacy-sensitive infrastructure, not a casual chat analyzer.

Architecture Guidelines

• Prefer source adapters over duplicating DB reverse engineering logic.
• The first source adapter should integrate with kakaocli or the k-skill kakaotalk-mac helper.
• Keep ingestion, normalized archive, keyword search, semantic search, and skill wrapper as separable modules.
• Use stable message identifiers and incremental cursors so indexing can resume without rereading everything.
• Keep the agent skill thin: it should call the CLI and summarize results, not own indexing logic.

Development Guidelines

• Add tests before behavior changes.
• Use fixtures with synthetic chat data only.
• Do not create tests that depend on the user's real KakaoTalk installation or real local DB.
• Real KakaoTalk smoke tests may be manual-only and must avoid printing private content.
• Nothing derived from a real archive may be committed, including in documentation. This repository is public; the archive it reads is not. Avoiding private content in session output is not enough, because a finding made while looking at live data tends to get written down next to the rule it justified — a quoted message, a room name, a person's name or kinship term, a sample used because it was at hand. Skill files, comments, tests, and changelogs are all published. State the rule and drop the evidence: the observation that convinced you is for this conversation, not for the commit. Fixtures stay synthetic even when a real value would have been easier to paste.
• Keep README, CLI help, and privacy behavior aligned in the same change.
• Verify against the toolchain CI pins, and run every gate CI runs. .github/workflows/ci.yml pins the Rust version (matching rust-version in Cargo.toml) and runs five gates: cargo fmt --all -- --check, cargo clippy --all-targets -- -D warnings, cargo test --all-targets, cargo publish --dry-run, and scripts/verify_release_config.py. A newer local toolchain passes work that CI rejects, because clippy retires and re-scopes lints between releases — so cargo +<pinned> clippy is the check that counts. Running a subset and reporting it as green is the failure mode this exists to prevent.