fkf: Instructions file for Codex

AGENTS.md

FKF is one typed Python package and one console command. Its purpose is to keep a person's or team's knowledge in plain files (Markdown notes, JSON Lines records) and let agents search and read it offline. The README describes the product; this file defines implementation boundaries.

Scope

• Keep only the current configuration and base format. Do not add legacy code, migration tooling, provider SDKs or compatibility command surfaces.
• projects/, tasks/ and wiki/ contain authored Markdown; wiki concepts follow OKF v0.2. Tasks use tasks/YYYY-MM-DD_slug/TASK.md plus inputs/ and outputs/. records/<source>/<YYYY-MM>.jsonl holds one line per source item, upserted by id (undated.jsonl, snapshot.jsonl for snapshot sources). .fkf/ is a disposable SQLite cache. sources/ holds collectors, scripts/, configs/ and tests/ base maintenance, skills/ workflow packages. One fkf.yaml (version 2) defines the base; ~/.config/fkf/config.yaml registers bases per user and grants collection trust per machine.
• Records have id, title, optional text, time, url, links, aliases and attributes. Provider-specific projection belongs in base-owned collectors. Reserved attributes updated, observed and partial describe revision provenance. No provider SDK, model, embedding, scheduler, harness installer or plugin framework belongs in the core.
• CLI and MCP call the same services. MCP exposes exactly search and read, with no execution or write operation.

Invariants

• Search and read never run collectors or contact the network. They may refresh the disposable cache incrementally; a file that fails to parse is skipped and reported, never fatal. FTS uses quoted literal terms; SQL uses parameters.
• Every result carries a readable ref that resolves to a file: path, path#section or source:id. The cache may locate a record, but the answer always comes from the record file.
• Explicit aliases and links provide identity and relationship evidence; prose and name similarity never create relations.
• Use the confined Store for base access. Refuse symlinks and special files below the base, bound traversal and bytes, write atomically, and serialize writers by physical base identity. Private lock, run state, usage counts and collector logs stay outside the base; usage never records queries or refs.
• Collection is explicit, uses direct configured argv from the base root, and requires per-machine trust in the user configuration. Remove loader-injection variables, kill process groups on timeout, cancellation or output overflow, write nothing on provider failure and recover interrupted commits from records/.pending/, and keep provider stdout/stderr out of errors (stderr goes to a bounded private log).
• Files are the only source of truth. Deleting .fkf/ or the state directory loses nothing but convenience.