{
  "markdown": "# Personal Knowledge System\n\nPKS is Arjun's source-backed memory service for AI assistants. Production is a\nsingle read-only, source-first system: it builds immutable evidence generations\nfrom authoritative project files, explicit operating-memory files, curated\nrecords, and a bounded window of recent Claude Code and Codex sessions.\n\nThe older entry store, tiers, salience, reconsolidation, and Dream machinery\nremain in the repository as legacy code and audit history. They do not maintain\nor validate the production corpus.\n\n## Production architecture\n\nOne complete generation contains:\n\n- authoritative README, PRD, spec, report, handoff, FABLE, and ARJUN files;\n- explicitly configured operating-policy and curated-memory files;\n- recent redacted Claude Code and Codex conversational context;\n- a project catalog derived from real source folders and timestamps;\n- vectors, exact-identifier maps, project maps, source-family maps, checksums,\n  suppressions, and a manifest under the same generation ID.\n\nRecent sessions are not a second memory lane. They use the same\n`EvidenceRecord`, publication transaction, vector namespace, Redis namespace,\nand search calculation as durable files. They are marked `working_context`,\nretain lower authority than durable sources, and receive only a small\nsemantic-relevance-gated attention lift with a three-day half-life.\nRetrieval-validation prompts and PASS/FAIL reports are excluded before\nchunking so probe vocabulary cannot become self-retrieving working context.\n\n## Retrieval contract\n\nThe live Cloudflare Worker is under `cloudflare-mcp/mcp-server/` and production\nsets `SOURCE_FIRST_MODE=on`.\n\nSearch uses one transparent score:\n\n```text\nbase_score =\n    0.70 * semantic_similarity\n  + 0.15 * lexical_overlap\n  + 0.10 * source_authority\n  + 0.05 * source_recency\n\nworking_context_bonus =\n    0.04 * semantic_similarity * exp(-ln(2) * age_days / 3)\n\nfinal_score = min(1, base_score + working_context_bonus)\n```\n\nExact identifiers, strong exact lexical phrases, and explicitly named projects\nreceive deterministic candidate recovery and retain ordering priority.\nByte-identical evidence collapses on `content_checksum`, with alternate source\npaths retained. General results must clear a `0.65` final-score floor; otherwise\nthe service explicitly abstains and returns no evidence.\n\nThe main read tools are:\n\n- `get_index` — current generation and project catalog;\n- `search` / `get_context` — source-backed excerpts and score components;\n- `get_deep` — every sibling chunk from one `ev_*` evidence source;\n- `get_validation_status` — current source-first generation and freshness;\n- `get_dream_summary` — the same source-first status plus explicit notice that\n  Dream is retired from production maintenance;\n- `health` — Worker build identity, generation, and source/session freshness.\n\nLegacy write and Dream tools may remain in the MCP schema for compatibility.\nThey are disabled or non-authoritative in production source-first mode.\n\n## Atomic rebuild and scheduling\n\n`.github/workflows/source-first-rebuild.yml` is the only scheduled production\nmaintenance path. GitHub schedules it every two hours on the self-hosted macOS\nrunner that can read the local Dropbox and agent-session sources. There is no\nPKS serving LaunchAgent or local cron.\n\nEach run:\n\n1. scans, redacts, chunks, and checksums all configured evidence;\n2. stages a complete candidate without moving `sf:current_generation`;\n3. verifies Redis records, vectors, project maps, and source maps;\n4. runs the exact production Worker retrieval implementation against the staged\n   generation, including negative-control abstention;\n5. promotes by writing the heartbeat and live pointer only after every gate\n   passes;\n6. verifies the now-serving generation and uploads text-free build diagnostics.\n\nA failed scan, publish, verification, or retrieval evaluation leaves the last\ngood generation live.\n\n## Commands\n\nBuild local artifacts without remote writes:\n\n```bash\ningestion/.venv/bin/python scripts/source_first_rebuild.py\n```\n\nStage a remote candidate without moving the serving pointer:\n\n```bash\ningestion/.venv/bin/python scripts/source_first_rebuild.py --stage\n```\n\nVerify or promote a staged generation:\n\n```bash\ningestion/.venv/bin/python scripts/source_first_rebuild.py --verify-generation sf_YYYYMMDDTHHMMSSZ\ningestion/.venv/bin/python scripts/source_first_rebuild.py --promote-generation sf_YYYYMMDDTHHMMSSZ\n```\n\nVerify production freshness and storage completeness:\n\n```bash\ningestion/.venv/bin/python scripts/source_first_rebuild.py --verify-current --max-age-hours 36\n```\n\nRun focused tests:\n\n```bash\ningestion/.venv/bin/python -m unittest discover -s tests/python -p 'test_source_first.py'\ncd cloudflare-mcp/mcp-server\nnpm run type-check\nnpm run test:worker -- test/sourceFirst.test.ts\n```\n\nDeploy the production Worker:\n\n```bash\nbash scripts/deploy_cloudflare_worker.sh\n```\n\n## Source map\n\n- `shared/source_first_config.json` — source roots, bounds, authority, and\n  recent-session policy;\n- `ingestion/source_first/scanner.py` — authoritative file discovery;\n- `ingestion/source_first/session_scanner.py` — direct session parsing,\n  mapping, bounds, and pre-persistence redaction;\n- `ingestion/source_first/models.py` — unified immutable evidence contract;\n- `ingestion/source_first/publisher.py` — staged storage, verification, and\n  promotion;\n- `scripts/source_first_rebuild.py` — build/operator CLI;\n- `cloudflare-mcp/mcp-server/src/sourceFirst.ts` — production retrieval and\n  operational health;\n- `tests/probes/` — deterministic retrieval probes;\n- `docs/source-first-memory.md` — detailed product and operator contract;\n- `docs/pks-source-first-cutover-completion-2026-08-10.md` — deployed-state\n  verification and acceptance evidence;\n- `openwiki/quickstart.md` — code-grounded navigation.\n\n## Legacy boundary\n\nThe following are not production-serving sources of truth:\n\n- `ke_*` entries and the old thin index;\n- tier counts, salience, access-count reinforcement, and reconsolidation;\n- Dream runs, validation ledgers over the old entry store, and local nightly\n  ingestion success markers;\n- `mcp-server/`, the older Vercel MCP implementation.\n\nUse them only for explicit legacy investigation. A green legacy gate does not\nprove the production source-first corpus is healthy, and a red legacy Dream\nledger does not make the production corpus unhealthy.\n",
  "bytes": 6395,
  "sha": "57a5d07212f0574cba19b644c8ca56ebb9ae4cd9594883d1330add26a29e7c69",
  "repo_slug": "arjundivecha/personal-knowledge-system",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_arjundivecha_personal_knowledge_system_o_a61e3e25/readme"
}