CodeLore: Ambient Codebase Tips for AI Coding Sessions

The core insight: Context decay in AI-assisted development is an attention problem, not a storage problem. AGENTS.md already holds the lore. Humans don't re-read it. The fix is a single landmine at the right moment — not a bigger document.

The problem

Coding agents (Claude Code, Grok, Cursor, Codex) change the unit of work from "a function" to "a PR-shaped pile." Three failure modes show up within a week:

Symptom	Why it happens
You merge agent code and forget why a redaction lives in two modules	Chat died; the decision never made it into a place you re-read
A new teammate (or future you) trips the same footgun	`CLAUDE.md` is 400 lines; nobody scrolls to "Never Do" on session three
SessionStart is full of tooling hooks but zero human context	Hooks fire for telemetry and init — not for tribal knowledge

Static docs help agents. They rarely help humans at the moment of starting work. IDE tours (CodeTour) help onboarding once. Neither solves ambient re-exposure while you're already mid-flow with an LLM.

What CodeLore is

CodeLore is a small open-source tool that runs when an AI session starts:

Resolve the codebase — git root, or frecency-pick under a multi-repo parent like ~/code
Pick one tip — curated local packs first; filtered auto-extract from CLAUDE/AGENTS/git as backup
Deliver without hijacking you — full-width terminal banner + optional macOS toast (× dismiss, hover pauses, no focus steal)
Log locally — ~/.tips/tips-log.md; seen-state under ~/.codelore/state/

Important design choice: tip data never ships in the package. Your packs live in your repos under .codelore/tips/. The OSS repo is the engine.

Loading diagram...

Architecture decisions that mattered

Local-first, package-only open source

Early versions accidentally mixed dogfood tip packs into the git history. That was wrong for two reasons: private lore shouldn't live next to a public tool, and OSS consumers shouldn't inherit your monorepo's landmines.

The fix:

.gitignore for .codelore/tips/** and tip logs
History rewrite so pack JSON never appears on main
Public repo ships CLI + toast binary source + format docs only

Consumer repos keep packs privately. That split is load-bearing.

Delivery: not Notification Center

macOS Notification Center banners are intentionally tiny. Modal dialogs steal focus and block work. CodeLore's default is a custom non-activating AppKit panel:

Top-right, below the menu bar
Full tip text (no ellipsis) — the card grows
Severity as a text badge + accent edge (not color alone — a11y)
× or click to dismiss; hover pauses the auto-hide timer
8s / 12s / 16s dwell by tier

Terminal always gets a full-width box so SSH and headless sessions still work.

Cooldown vs dwell

Timer	Default	Why
Gap between tips per repo	30 minutes	Avoid spam across restarts
Toast on-screen	8–16s by tier	Enough to read; hover if you need more
`--force`	bypass cooldown	Dogfood and demos

SessionStart hooks use --reason session-start so failures exit 0 — a broken tip tool must never brick Claude.

Ranking (simple, opinionated)

When a curated pack exists (≥8 tips), human lore dominates. Auto-extract prefers NEVER/MUST bullets over README marketing (✅ Feature Name). Package-aware scoring prefers tips whose paths/tags match the cwd package in a monorepo.

Tip pack shape (local only)

json

{
  "version": 1,
  "tips": [
    {
      "id": "unique-kebab-id",
      "title": "Short headline",
      "body": "Full action-first tip — complete sentences, no mid-word truncation.",
      "tier": "critical",
      "tags": ["security"],
      "paths": ["backend/app/core/"],
      "source": "human"
    }
  ]
}

Drop files under <repo>/.codelore/tips/*.json. Nested package git roots walk parents so a monorepo pack applies to backend/ and frontend/ checkouts.

How to try it

bash

git clone https://github.com/xlreon/codelore.git
cd codelore
node poc/codelore.mjs select --cwd ~/code --all
node poc/codelore.mjs tip --cwd ~/path/to/your/repo --force
bash poc/macos/build.sh   # optional toast

Wire SessionStart once (path absolute), open a new Claude Code session in a git repo, look top-right.

What it's not

Not a replacement for CLAUDE.md or GitNexus impact analysis
Not a cloud knowledge base or team wiki SaaS
Not finished product: no npm publish yet, no harvest/approve workflow, no Windows toast

It's the smallest layer that puts one human-relevant fact in the path of an AI session.

Status

Open source, MIT: github.com/xlreon/codelore

If you use AI agents daily and keep re-learning the same gotchas, clone it, seed a private pack, and put the hook on SessionStart. The package is the drip; your lore stays yours.