# iknowyou — Roadmap

**Status as of 2026-02-25**

## Vision

iknowyou is a communication learning engine. It observes how people communicate, extracts structured signals, and assembles briefs that help an LM talk to each person the way they actually want to be talked to.

**Aeries** is the first product built on iknowyou — an AI companion that learns who you are through natural conversation.

## Milestone Summary

| # | Name | Proves | Status |
|---|------|--------|--------|
| M1 | Chat Interface | Streaming chat with vLLM works end-to-end | COMPLETE |
| M2 | Memory Layer (Synap) | Conversations persist, memories accumulate, observer extracts learnings | COMPLETE |
| M3 | Deep Observer | Rich signal extraction from every exchange — style, topics, facts, emotion, dynamics | COMPLETE |
| M4 | Cohort Engine | People are clustered by behavior; new users get intelligent cold-start priors | COMPLETE |
| M5 | Communication Brief | Full brief assembly from signals + observations + cohorts → injected into system prompt | IN PROGRESS |
| M6 | Closed Loop | Complete observe → learn → brief → generate cycle running continuously | PLANNED |
| M7 | Adaptation Proof | Measurable evidence that Aeries communicates differently with different people | PLANNED |

---

## Completed

### M1: Chat Interface (COMPLETE)

Aeries streams responses from Qwen3-8B via vLLM. Clean dark UI, responsive layout.

**Delivered:**
- Next.js 15 + React 19 + Tailwind v4 (OKLCH dark theme)
- SSE streaming from vLLM OpenAI-compatible API
- Zustand state management
- Port 59521 (tidalDB convention)

### M2: Memory Layer — Synap (COMPLETE)

Conversations persist across sessions. Observer extracts learnings and stores them as memories. Recalled memories are injected into system prompt before generation.

**Delivered:**
- Synap HTTP client (`lib/synap.ts`)
- Messages stored in Synap Conversational API (user + assistant)
- Conversation sidebar with persistence (localStorage + Synap)
- Memory recall before generation (top 5 vivid memories injected)
- Async observer: extracts observations via Qwen3, stores as semantic memories
- Casual, question-forward system prompt

---

### M3: Deep Observer (COMPLETE)

Two-tier observer: Tier 1 extracts full `ObserverOutput` (engagement, style, topic, dynamics) on every exchange. Tier 2 synthesizes natural-language observations every 5 turns.

**Delivered:**
- Full `ObserverOutput` schema extraction via Qwen3-8B (4 dimensions, 20 fields)
- Dimension-tagged signal storage in Synap (`signal:style`, `signal:topic`, etc.)
- Resilient JSON parsing (no structured output mode — manual extraction)
- Turn tracking + signal buffering per conversation
- Tier 2 synthesis: 1-3 natural-language pattern observations every 5 turns
- Structured signal context in system prompt (grouped by dimension)
- Locally-computed fields: word count, response latency (not LM-extracted)

---

### M4: Cohort Engine (COMPLETE)

Person identity and behavioral cohort classification. Cold-start priors from similar people so the first response is already slightly adapted.

**Delivered:**
- Person identity: `personId` (UUID) generated on first visit, persisted in localStorage, passed in every chat request
- Person switcher UI in sidebar for testing multi-person scenarios
- 9 rule-based cohort definitions: casual, formal, technical, accessible, leader, responder, positive-engager, verbose, terse
- `PersonProfile`: running-average signal aggregation per person (formality, sentiment, word count, jargon rate, leader rate, top specificity, top domains)
- Soft cohort assignment (0-1 probability, not mutually exclusive — a person can be `casual + technical + leader`)
- Cold-start flow: new person → load cohort priors from Synap → weight by `1/(1 + interactionCount/10)` → fades as individual data grows
- All signals and observations tagged with `person:{id}` for person-scoped recall
- Cohort priors injected into system prompt as `[Cohort insights — people like them]` section
- Profile persistence in Synap + in-memory cache
- Profile updated after every observer extraction (running average blended with existing)

**Key files:**
- `lib/cohorts.ts` — cohort engine: definitions, profile computation, assignment, prior loading, Synap persistence
- `lib/types.ts` — `PersonProfile`, `CohortDefinition`, `CohortMembership`
- `lib/observer.ts` — person-tagged signals and observations
- `lib/store.ts` — `personId` state + `switchPerson()` action
- `lib/vllm.ts` — cohort priors in system prompt
- `app/api/chat/route.ts` — profile loading, prior injection, post-observer profile update
- `components/sidebar/person-switcher.tsx` — identity display + switch button

**Deferred:**
- Temporal cohorts (morning/night, burst/steady) — not enough signal data yet; revisit in M6
- Automatic cohort discovery from data — rule-based is sufficient; revisit when person count > 50

---

## In Progress

### M5: Communication Brief

**Thesis:** The brief is the interface between learning and generation. It's a structured profile of everything the system knows about this person, assembled fresh before every response.

**Status:** Core implementation is live (brief assembly, brief inspection API, prompt injection). Acceptance validation is still pending.

**What changes:**
- Full brief assembly from architecture spec:
  - Hot/cold topics with velocity
  - Style profile (formality, length, structure, jargon, emoji)
  - Timing patterns (active hours, response latency)
  - What works / what doesn't (patterns, not individual messages)
  - Relevant observations (semantic retrieval)
  - Cohort priors (for sparse dimensions)
- Brief is structured JSON, converted to system prompt guidelines
- Brief inspection endpoint for debugging/trust

**Key files:**
- `lib/briefing.ts` — brief assembly from Synap queries
- `lib/vllm.ts` — system prompt built from brief, not static text
- `app/api/brief/[personId]/route.ts` — inspection endpoint

**Acceptance:**
- Brief contains ≥4 populated sections for a person with 10+ interactions
- Brief changes meaningfully between conversations as signals accumulate
- LM output visibly adapts when brief content changes

## Planned

### M6: Closed Loop

**Thesis:** The full observe → learn → brief → generate cycle runs continuously. Every exchange makes Aeries slightly better at talking to this person.

**What changes:**
- Session mechanics: conversations as sessions with open/close lifecycle
- Signal promotion: session signals aggregate into global profile on close
- Preference vector evolution: EMA blend of positively-received message embeddings
- Periodic observation generation (every 5 turns + session close)
- Contradiction resolution via confidence decay (no explicit deletion)
- Observation reinforcement: same pattern observed again → confidence refreshed

**Key files:**
- `lib/session.ts` — new: session lifecycle
- `lib/observer.ts` — periodic observation triggers
- `lib/briefing.ts` — preference vector queries
- `app/api/chat/route.ts` — full loop orchestration

**Acceptance:**
- 20-turn conversation produces measurable preference drift
- Brief changes between turns (not just between sessions)
- Observation confidence decays over time, reinforcement works

### M7: Adaptation Proof

**Thesis:** Prove that the system actually communicates differently with different people. Measurable, inspectable, demonstrable.

**What changes:**
- A/B testing: same question to two people with different profiles → different Aeries responses
- Brief diff viewer: side-by-side comparison of two person briefs
- Adaptation metrics: response style variance across people, convergence speed
- Trust UI: what Aeries knows about you, with inspection and correction

**Acceptance:**
- Two people with 15+ interactions each receive measurably different responses to the same prompt
- Adaptation speed: style convergence within 5 conversations
- User can inspect and correct what Aeries has learned