# Context Layer (Phase 7)

## `kb context` — Compressed Entity Index

Generates a ~30-line compressed index of all entities (people, projects, teams) and key terms. Designed to give AI agents enough context to know everyone and everything by name without consuming the full instruction budget.

### Usage

```bash
kb context                           # full compressed index (plain text)
kb context --json                    # structured JSON output
kb context --for "Rust migration"    # filtered to relevant entities only
```

### Plain text output format

```
# Knowledge Base Context
|67 entities, 3096 documents, 2024-06 to 2026-02

## People (27)
|Carol(Platform Lead) Dave(Head of Product) Eve(Cloud Migration Lead)
→ Details: `kb entity find "name" --json`

## Projects (12)
|Cloud Migration(Eve,In Progress) Scanner v2(Frank,Planning)
→ Details: `kb entity find "project" --json`

## Teams (8)
|Platform(PLAT) Engine(ENG) Security(SEC)

## Terms
|GIM=Internal Monorepo MR=Merge Request
→ Full glossary: `kb view memory/glossary.md`
```

### JSON output

```json
{
  "text": "# Knowledge Base Context\n...",
  "stats": {
    "documents": 3096,
    "entities": 67,
    "date_range": {"earliest": "2024-06-01", "latest": "2026-02-14"}
  },
  "entities": [
    {"name": "Carol Nguyen", "entity_type": "person", "mention_count": 45},
    {"name": "Cloud Migration", "entity_type": "project", "mention_count": 32}
  ]
}
```

### Topic filtering (`--for`)

When a topic is provided, the command:
1. Runs an FTS search for the topic
2. Collects entity IDs mentioned in matching documents
3. Filters the output to only those entities
4. Adjusts the header: `# Context: Rust migration`

This is useful for scoping context to a specific conversation topic.

## `kb memory add` — Fact Recording

Records facts about entities, appending to both the SQLite database and the entity's markdown source file.

### Usage

```bash
kb memory add "Promoted to Staff Engineer" --entity "Bob" --date 2026-01-19
kb memory add "Led Platform TF kickoff" --entity "Carol"
```

### How it works

1. Finds the entity by name (case-insensitive, partial match)
2. Inserts a row into the `facts` SQLite table
3. If the entity has a `source_path` (e.g. `memory/people/bob-chen.md`), appends the fact under a `## Recent Facts` section in that file

### File format

Facts are appended as markdown list items:

```markdown
## Recent Facts
- [2026-01-19] Promoted to Staff Engineer
- [2026-02-01] Led Platform TF kickoff
```

## `kb memory list` — List Facts

```bash
kb memory list                     # all facts
kb memory list --since 30          # last 30 days
kb memory list --json              # structured output
```

### Schema

The `facts` table is created via migration `002_create_facts_table`:

```sql
CREATE TABLE IF NOT EXISTS facts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    entity_id INTEGER REFERENCES entities(id),
    fact_text TEXT NOT NULL,
    fact_date TEXT,
    created_at TEXT NOT NULL DEFAULT (datetime('now'))
)
```

## How Context Replaces CLAUDE.md Tables

Previously, CLAUDE.md contained ~100 lines of People, Terms, Projects, Customers, and Tools tables. These are now dynamically generated by `kb context` from:

- **People**: Entity DB (`entity_type='person'`), sorted by mention count
- **Projects**: Entity DB (`entity_type='project'`), with lead and status
- **Teams**: Entity DB (`entity_type='team'`), with abbreviations
- **Terms**: Parsed from `memory/glossary.md`

CLAUDE.md now contains only: Me (intro), Knowledge Base (kb commands), Scripts (organise_granola.py), and Preferences.

The memory files (`memory/people/`, `memory/projects/`, etc.) remain the source of truth for entity seeding. `kb context` reads from the indexed database, not directly from files.
