---
source: raw/schema.sql
content_hash: 71b47e47b483834c887de14c76d5b16506d90ad64198d76a92a7b3731132dab8
namespace: work
last_synced: 2026-05-31
confidence: 0.9
tags: [personal-os, postgres, schema, database]
---

# Personal OS — Postgres Schema

The `personal_os` Postgres database is the system of record for Asana sync,
agent annotations, wiki sources, and semantic memory. Extensions: `vector`
(pgvector) and `pg_trgm`.

## Core Asana Tables

### `tasks`
One row per Asana task GID, upserted on every sync. Tracks name, notes
(plain + HTML), due/start dates, completion, assignee, creator, project
membership, and a `source` enum:

- `my_tasks` — assigned to me, in My Tasks sections
- `following` — I'm a follower (CC'd, commented)
- `delegated` — I created it, someone else is assignee
- `project` — member of a project, not otherwise classified

Sync bookkeeping: `fetched_at`, `stories_fetched_before` (cursor for
incremental story pulls), `raw_json` (full Asana response).

Later additions: `namespace` (default `work`), `possibly_deleted`,
`last_seen_in_full_sync`.

Indexes cover modified time, due date (partial WHERE NOT completed),
section, assignee, source, completed, and trigram on `name` for fuzzy
search.

### `stories`
Raw event log per task. `resource_subtype` is Asana's event type
(`comment_added`, `assigned`, `due_date_changed`, `section_changed`,
`dependency_added`, `attachment_added`, `marked_complete`, etc.). Stores
both plain text and HTML so embedded task GID refs can be parsed out.

### `task_edges`
Directed graph between tasks. `relation_type`:

- `subtask` — related is a subtask of task
- `dependency` — task is blocked by related
- `dependent` — task is blocking related
- `project_sibling` — same project + section
- `mention` — related was referenced in a story on task

Composite PK `(task_gid, related_gid, relation_type)`. `related_gid` may
not yet exist in `tasks`.

### `task_annotations`
Agent-written (or user-written) tags. `annotation_type`: `irrelevant`,
`watching`, `needs_action`, `snoozed`. Includes agent reasoning note and
`snoozed_until` date. `annotated_by` distinguishes agent vs user.

### `sync_state`
One row per logical sync stream keyed by stream name (`my_tasks`,
`following`, `delegated`, `project:{gid}`, `workspace_events`). Stores
`cursor` (ISO timestamp or events sync_token) and `full_sync_at` for
when the last full pull happened.

## Vector / Wiki / Memory Tables

### `task_embeddings`
Voyage AI 1024-dim vectors with HNSW cosine index for semantic task
search.

### `file_references`
Tracks files (macOS security-scoped bookmarks in `bookmark_data`) and
web URLs that should be ingested into the wiki. `content_hash` for
incremental sync, `wiki_stale=true` triggers reprocessing,
`modification_log` keeps before/after hash history. Namespace constrained
to `work | personal | family`.

### `wiki_pages`
LLM-synthesised wiki entries (NOT raw copies). Carries `sources` JSONB,
`confidence` float, `superseded_by` self-ref for version chains,
`last_synced_hash`, and a 1536-dim embedding for semantic search. **Note:
the live system has moved off this table** — the wiki now lives in the
Obsidian vault (`~/obsidian/wiki/`) and uses file-frontmatter hashing
instead. See [[wiki-ingest-process]].

### `memory_store`
Semantic memory accumulated from Discord/Claude/manual sources.
`type`: `fact | preference | decision | person`. Carries entity refs in
JSONB, 1536-dim embedding, optional `expires_at` (null = permanent).

## Views

### `active_tasks`
Convenience view: non-completed, non-irrelevant, non-snoozed tasks
joined with their annotations. Ordered by source priority
(`my_tasks > delegated > following > project`), then due date, then
modified date. Used as the starting point for the agent's daily review.

## Migration Tables (Catch-Up Plan 2026-04-27)

Three additions land via the catch-up plan and are referenced by the
state doc as `✅` applied:

- `corrections_log` — Tactic records pushback, Retrospector aggregates
  patterns by `reason_tag` and `week_number`.
- `executor_runs` — state machine row per Executor task (states:
  `analyzing → awaiting_analysis_approval → fixing → pr_open →
  ci_running → ci_failed → awaiting_user → complete | abandoned`).
- `activity_daily.quadrant` — column added for weekly drift detection
  (`project | aor | career | strategy | other`).

See [[personal-os-catchup-plan-2026-04-27]] for the rationale (DB over
markdown/YAML, extend existing components).

## Related
[[personal-os-state-2026-04-27]] [[personal-os-catchup-plan-2026-04-27]] [[wiki-ingest-process]]