htm 0.0.1 → 0.0.2

data/db/schema.sql

@@ -82,16 +82,14 @@ ALTER SEQUENCE public.node_tags_id_seq OWNED BY public.node_tags.id;
 CREATE TABLE public.nodes (
     id bigint NOT NULL,
     content text NOT NULL,
-    source text DEFAULT ''::text,
     access_count integer DEFAULT 0 NOT NULL,
     created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
     updated_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
     last_accessed timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
     token_count integer,
-    in_working_memory boolean DEFAULT false,
-    robot_id bigint NOT NULL,
     embedding public.vector(2000),
     embedding_dimension integer,
+    content_hash character varying(64),
     CONSTRAINT check_embedding_dimension CHECK (((embedding_dimension IS NULL) OR ((embedding_dimension > 0) AND (embedding_dimension <= 2000))))
 );
 
@@ -107,12 +105,6 @@ COMMENT ON TABLE public.nodes IS 'Core memory storage for conversation messages
 
 COMMENT ON COLUMN public.nodes.content IS 'The conversation message/utterance content';
 
---
--- Name: COLUMN nodes.source; Type: COMMENT; Schema: public; Owner: -
---
-
-COMMENT ON COLUMN public.nodes.source IS 'From where the content came (empty string if unknown)';
-
 --
 -- Name: COLUMN nodes.access_count; Type: COMMENT; Schema: public; Owner: -
 --
@@ -143,18 +135,6 @@ COMMENT ON COLUMN public.nodes.last_accessed IS 'When this memory was last acces
 
 COMMENT ON COLUMN public.nodes.token_count IS 'Number of tokens in the content (for context budget management)';
 
---
--- Name: COLUMN nodes.in_working_memory; Type: COMMENT; Schema: public; Owner: -
---
-
-COMMENT ON COLUMN public.nodes.in_working_memory IS 'Whether this memory is currently in working memory';
-
---
--- Name: COLUMN nodes.robot_id; Type: COMMENT; Schema: public; Owner: -
---
-
-COMMENT ON COLUMN public.nodes.robot_id IS 'ID of the robot that owns this memory';
-
 --
 -- Name: COLUMN nodes.embedding; Type: COMMENT; Schema: public; Owner: -
 --
@@ -167,6 +147,12 @@ COMMENT ON COLUMN public.nodes.embedding IS 'Vector embedding (max 2000 dimensio
 
 COMMENT ON COLUMN public.nodes.embedding_dimension IS 'Actual number of dimensions used in the embedding vector (max 2000)';
 
+--
+-- Name: COLUMN nodes.content_hash; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.nodes.content_hash IS 'SHA-256 hash of content for deduplication';
+
 --
 -- Name: nodes_id_seq; Type: SEQUENCE; Schema: public; Owner: -
 --
@@ -184,6 +170,74 @@ CREATE SEQUENCE public.nodes_id_seq
 
 ALTER SEQUENCE public.nodes_id_seq OWNED BY public.nodes.id;
 
+--
+-- Name: robot_nodes; Type: TABLE; Schema: public; Owner: -
+--
+
+CREATE TABLE public.robot_nodes (
+    id bigint NOT NULL,
+    robot_id bigint NOT NULL,
+    node_id bigint NOT NULL,
+    first_remembered_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+    last_remembered_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+    remember_count integer DEFAULT 1 NOT NULL,
+    created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+    updated_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP
+);
+
+--
+-- Name: TABLE robot_nodes; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON TABLE public.robot_nodes IS 'Join table connecting robots to nodes (many-to-many)';
+
+--
+-- Name: COLUMN robot_nodes.robot_id; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.robot_nodes.robot_id IS 'ID of the robot that remembered this node';
+
+--
+-- Name: COLUMN robot_nodes.node_id; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.robot_nodes.node_id IS 'ID of the node being remembered';
+
+--
+-- Name: COLUMN robot_nodes.first_remembered_at; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.robot_nodes.first_remembered_at IS 'When this robot first remembered this content';
+
+--
+-- Name: COLUMN robot_nodes.last_remembered_at; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.robot_nodes.last_remembered_at IS 'When this robot last tried to remember this content';
+
+--
+-- Name: COLUMN robot_nodes.remember_count; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.robot_nodes.remember_count IS 'Number of times this robot has tried to remember this content';
+
+--
+-- Name: robot_nodes_id_seq; Type: SEQUENCE; Schema: public; Owner: -
+--
+
+CREATE SEQUENCE public.robot_nodes_id_seq
+    START WITH 1
+    INCREMENT BY 1
+    NO MINVALUE
+    NO MAXVALUE
+    CACHE 1;
+
+--
+-- Name: robot_nodes_id_seq; Type: SEQUENCE OWNED BY; Schema: public; Owner: -
+--
+
+ALTER SEQUENCE public.robot_nodes_id_seq OWNED BY public.robot_nodes.id;
+
 --
 -- Name: robots; Type: TABLE; Schema: public; Owner: -
 --
@@ -192,8 +246,7 @@ CREATE TABLE public.robots (
     id bigint NOT NULL,
     name text,
     created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
-    last_active timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
-    metadata jsonb
+    last_active timestamp with time zone DEFAULT CURRENT_TIMESTAMP
 );
 
 --
@@ -220,12 +273,6 @@ COMMENT ON COLUMN public.robots.created_at IS 'When the robot was first register
 
 COMMENT ON COLUMN public.robots.last_active IS 'Last time the robot accessed the system';
 
---
--- Name: COLUMN robots.metadata; Type: COMMENT; Schema: public; Owner: -
---
-
-COMMENT ON COLUMN public.robots.metadata IS 'Robot-specific configuration and metadata';
-
 --
 -- Name: robots_id_seq; Type: SEQUENCE; Schema: public; Owner: -
 --
@@ -296,6 +343,65 @@ CREATE SEQUENCE public.tags_id_seq
 
 ALTER SEQUENCE public.tags_id_seq OWNED BY public.tags.id;
 
+--
+-- Name: working_memories; Type: TABLE; Schema: public; Owner: -
+--
+
+CREATE TABLE public.working_memories (
+    id bigint NOT NULL,
+    robot_id bigint NOT NULL,
+    node_id bigint NOT NULL,
+    added_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
+    token_count integer
+);
+
+--
+-- Name: TABLE working_memories; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON TABLE public.working_memories IS 'Per-robot working memory state (optional persistence)';
+
+--
+-- Name: COLUMN working_memories.robot_id; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.working_memories.robot_id IS 'Robot whose working memory this belongs to';
+
+--
+-- Name: COLUMN working_memories.node_id; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.working_memories.node_id IS 'Node currently in working memory';
+
+--
+-- Name: COLUMN working_memories.added_at; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.working_memories.added_at IS 'When node was added to working memory';
+
+--
+-- Name: COLUMN working_memories.token_count; Type: COMMENT; Schema: public; Owner: -
+--
+
+COMMENT ON COLUMN public.working_memories.token_count IS 'Cached token count for budget tracking';
+
+--
+-- Name: working_memories_id_seq; Type: SEQUENCE; Schema: public; Owner: -
+--
+
+CREATE SEQUENCE public.working_memories_id_seq
+    START WITH 1
+    INCREMENT BY 1
+    NO MINVALUE
+    NO MAXVALUE
+    CACHE 1;
+
+--
+-- Name: working_memories_id_seq; Type: SEQUENCE OWNED BY; Schema: public; Owner: -
+--
+
+ALTER SEQUENCE public.working_memories_id_seq OWNED BY public.working_memories.id;
+
 --
 -- Name: node_tags id; Type: DEFAULT; Schema: public; Owner: -
 --
@@ -308,6 +414,12 @@ ALTER TABLE ONLY public.node_tags ALTER COLUMN id SET DEFAULT nextval('public.no
 
 ALTER TABLE ONLY public.nodes ALTER COLUMN id SET DEFAULT nextval('public.nodes_id_seq'::regclass);
 
+--
+-- Name: robot_nodes id; Type: DEFAULT; Schema: public; Owner: -
+--
+
+ALTER TABLE ONLY public.robot_nodes ALTER COLUMN id SET DEFAULT nextval('public.robot_nodes_id_seq'::regclass);
+
 --
 -- Name: robots id; Type: DEFAULT; Schema: public; Owner: -
 --
@@ -320,6 +432,12 @@ ALTER TABLE ONLY public.robots ALTER COLUMN id SET DEFAULT nextval('public.robot
 
 ALTER TABLE ONLY public.tags ALTER COLUMN id SET DEFAULT nextval('public.tags_id_seq'::regclass);
 
+--
+-- Name: working_memories id; Type: DEFAULT; Schema: public; Owner: -
+--
+
+ALTER TABLE ONLY public.working_memories ALTER COLUMN id SET DEFAULT nextval('public.working_memories_id_seq'::regclass);
+
 --
 -- Name: node_tags node_tags_pkey; Type: CONSTRAINT; Schema: public; Owner: -
 --
@@ -334,6 +452,13 @@ ALTER TABLE ONLY public.node_tags
 ALTER TABLE ONLY public.nodes
     ADD CONSTRAINT nodes_pkey PRIMARY KEY (id);
 
+--
+-- Name: robot_nodes robot_nodes_pkey; Type: CONSTRAINT; Schema: public; Owner: -
+--
+
+ALTER TABLE ONLY public.robot_nodes
+    ADD CONSTRAINT robot_nodes_pkey PRIMARY KEY (id);
+
 --
 -- Name: robots robots_pkey; Type: CONSTRAINT; Schema: public; Owner: -
 --
@@ -355,6 +480,13 @@ ALTER TABLE ONLY public.schema_migrations
 ALTER TABLE ONLY public.tags
     ADD CONSTRAINT tags_pkey PRIMARY KEY (id);
 
+--
+-- Name: working_memories working_memories_pkey; Type: CONSTRAINT; Schema: public; Owner: -
+--
+
+ALTER TABLE ONLY public.working_memories
+    ADD CONSTRAINT working_memories_pkey PRIMARY KEY (id);
+
 --
 -- Name: idx_node_tags_node_id; Type: INDEX; Schema: public; Owner: -
 --
@@ -385,6 +517,12 @@ CREATE INDEX idx_nodes_access_count ON public.nodes USING btree (access_count);
 
 CREATE INDEX idx_nodes_content_gin ON public.nodes USING gin (to_tsvector('english'::regconfig, content));
 
+--
+-- Name: idx_nodes_content_hash_unique; Type: INDEX; Schema: public; Owner: -
+--
+
+CREATE UNIQUE INDEX idx_nodes_content_hash_unique ON public.nodes USING btree (content_hash);
+
 --
 -- Name: idx_nodes_content_trgm; Type: INDEX; Schema: public; Owner: -
 --
@@ -404,34 +542,40 @@ CREATE INDEX idx_nodes_created_at ON public.nodes USING btree (created_at);
 CREATE INDEX idx_nodes_embedding ON public.nodes USING hnsw (embedding public.vector_cosine_ops) WITH (m='16', ef_construction='64');
 
 --
--- Name: idx_nodes_in_working_memory; Type: INDEX; Schema: public; Owner: -
+-- Name: idx_nodes_last_accessed; Type: INDEX; Schema: public; Owner: -
 --
 
-CREATE INDEX idx_nodes_in_working_memory ON public.nodes USING btree (in_working_memory);
+CREATE INDEX idx_nodes_last_accessed ON public.nodes USING btree (last_accessed);
 
 --
--- Name: idx_nodes_last_accessed; Type: INDEX; Schema: public; Owner: -
+-- Name: idx_nodes_updated_at; Type: INDEX; Schema: public; Owner: -
 --
 
-CREATE INDEX idx_nodes_last_accessed ON public.nodes USING btree (last_accessed);
+CREATE INDEX idx_nodes_updated_at ON public.nodes USING btree (updated_at);
 
 --
--- Name: idx_nodes_robot_id; Type: INDEX; Schema: public; Owner: -
+-- Name: idx_robot_nodes_last_remembered_at; Type: INDEX; Schema: public; Owner: -
 --
 
-CREATE INDEX idx_nodes_robot_id ON public.nodes USING btree (robot_id);
+CREATE INDEX idx_robot_nodes_last_remembered_at ON public.robot_nodes USING btree (last_remembered_at);
 
 --
--- Name: idx_nodes_source; Type: INDEX; Schema: public; Owner: -
+-- Name: idx_robot_nodes_node_id; Type: INDEX; Schema: public; Owner: -
 --
 
-CREATE INDEX idx_nodes_source ON public.nodes USING btree (source);
+CREATE INDEX idx_robot_nodes_node_id ON public.robot_nodes USING btree (node_id);
 
 --
--- Name: idx_nodes_updated_at; Type: INDEX; Schema: public; Owner: -
+-- Name: idx_robot_nodes_robot_id; Type: INDEX; Schema: public; Owner: -
 --
 
-CREATE INDEX idx_nodes_updated_at ON public.nodes USING btree (updated_at);
+CREATE INDEX idx_robot_nodes_robot_id ON public.robot_nodes USING btree (robot_id);
+
+--
+-- Name: idx_robot_nodes_unique; Type: INDEX; Schema: public; Owner: -
+--
+
+CREATE UNIQUE INDEX idx_robot_nodes_unique ON public.robot_nodes USING btree (robot_id, node_id);
 
 --
 -- Name: idx_tags_name_pattern; Type: INDEX; Schema: public; Owner: -
@@ -446,11 +590,43 @@ CREATE INDEX idx_tags_name_pattern ON public.tags USING btree (name text_pattern
 CREATE UNIQUE INDEX idx_tags_name_unique ON public.tags USING btree (name);
 
 --
--- Name: nodes fk_rails_60162e9d3a; Type: FK CONSTRAINT; Schema: public; Owner: -
+-- Name: idx_working_memories_node_id; Type: INDEX; Schema: public; Owner: -
 --
 
-ALTER TABLE ONLY public.nodes
-    ADD CONSTRAINT fk_rails_60162e9d3a FOREIGN KEY (robot_id) REFERENCES public.robots(id) ON DELETE CASCADE;
+CREATE INDEX idx_working_memories_node_id ON public.working_memories USING btree (node_id);
+
+--
+-- Name: idx_working_memories_robot_id; Type: INDEX; Schema: public; Owner: -
+--
+
+CREATE INDEX idx_working_memories_robot_id ON public.working_memories USING btree (robot_id);
+
+--
+-- Name: idx_working_memories_unique; Type: INDEX; Schema: public; Owner: -
+--
+
+CREATE UNIQUE INDEX idx_working_memories_unique ON public.working_memories USING btree (robot_id, node_id);
+
+--
+-- Name: working_memories fk_rails_2c1d8b383c; Type: FK CONSTRAINT; Schema: public; Owner: -
+--
+
+ALTER TABLE ONLY public.working_memories
+    ADD CONSTRAINT fk_rails_2c1d8b383c FOREIGN KEY (node_id) REFERENCES public.nodes(id) ON DELETE CASCADE;
+
+--
+-- Name: working_memories fk_rails_4b7c3eb07b; Type: FK CONSTRAINT; Schema: public; Owner: -
+--
+
+ALTER TABLE ONLY public.working_memories
+    ADD CONSTRAINT fk_rails_4b7c3eb07b FOREIGN KEY (robot_id) REFERENCES public.robots(id) ON DELETE CASCADE;
+
+--
+-- Name: robot_nodes fk_rails_9b003078a8; Type: FK CONSTRAINT; Schema: public; Owner: -
+--
+
+ALTER TABLE ONLY public.robot_nodes
+    ADD CONSTRAINT fk_rails_9b003078a8 FOREIGN KEY (robot_id) REFERENCES public.robots(id) ON DELETE CASCADE;
 
 --
 -- Name: node_tags fk_rails_b51cdcc57f; Type: FK CONSTRAINT; Schema: public; Owner: -
@@ -466,8 +642,15 @@ ALTER TABLE ONLY public.node_tags
 ALTER TABLE ONLY public.node_tags
     ADD CONSTRAINT fk_rails_ebc9aafd9f FOREIGN KEY (node_id) REFERENCES public.nodes(id) ON DELETE CASCADE;
 
+--
+-- Name: robot_nodes fk_rails_f2fc98d49e; Type: FK CONSTRAINT; Schema: public; Owner: -
+--
+
+ALTER TABLE ONLY public.robot_nodes
+    ADD CONSTRAINT fk_rails_f2fc98d49e FOREIGN KEY (node_id) REFERENCES public.nodes(id) ON DELETE CASCADE;
+
 --
 -- PostgreSQL database dump complete
 --
 
-\unrestrict f5a75Zsnuw7NUeDmu1kxeQ3pRMbaORhrsWHJyDdXV4wbRfzQweTumJBXu85kf1z
+\unrestrict 6qynyffXXn5BTZM7u0DVZKV2Nc24dPezkY3OOwzriuYfchXNsoQuf114yBOqrIb

data/docs/api/database.md

@@ -264,241 +264,28 @@ htm = HTM.new(db_config: HTM::Database.default_config)
 
 ## Database Schema
 
-### Tables
+For detailed database schema documentation, see:
 
-#### `nodes`
+- **[Database Schema Documentation](../development/schema.md)** - Query patterns, optimization tips, and best practices
+- **[Database Tables Overview](../database/README.md)** - Auto-generated table reference with ER diagram
 
-Primary memory storage table (hypertable partitioned by `created_at`).
+### Quick Reference
 
-```sql
-CREATE TABLE nodes (
-  id SERIAL PRIMARY KEY,
-  key TEXT UNIQUE NOT NULL,
-  value TEXT NOT NULL,
-  type TEXT,
-  category TEXT,
-  importance REAL DEFAULT 1.0,
-  token_count INTEGER DEFAULT 0,
-  robot_id TEXT NOT NULL REFERENCES robots(id),
-  embedding vector(1536),
-  created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
-  last_accessed TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
-  in_working_memory BOOLEAN DEFAULT TRUE,
-  evicted_at TIMESTAMPTZ
-);
-
--- Indexes
-CREATE UNIQUE INDEX idx_nodes_key ON nodes(key);
-CREATE INDEX idx_nodes_created_at ON nodes(created_at DESC);
-CREATE INDEX idx_nodes_robot_id ON nodes(robot_id);
-CREATE INDEX idx_nodes_type ON nodes(type);
-CREATE INDEX idx_nodes_embedding ON nodes USING ivfflat (embedding vector_cosine_ops);
-CREATE INDEX idx_nodes_value_fts ON nodes USING GIN (to_tsvector('english', value));
-```
-
-#### `relationships`
-
-Node relationship graph.
-
-```sql
-CREATE TABLE relationships (
-  id SERIAL PRIMARY KEY,
-  from_node_id INTEGER NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
-  to_node_id INTEGER NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
-  relationship_type TEXT,
-  strength REAL DEFAULT 1.0,
-  created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
-  UNIQUE(from_node_id, to_node_id, relationship_type)
-);
-
--- Indexes
-CREATE INDEX idx_relationships_from ON relationships(from_node_id);
-CREATE INDEX idx_relationships_to ON relationships(to_node_id);
-```
-
-#### `tags`
-
-Flexible tagging system.
-
-```sql
-CREATE TABLE tags (
-  id SERIAL PRIMARY KEY,
-  node_id INTEGER NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
-  tag TEXT NOT NULL,
-  created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
-  UNIQUE(node_id, tag)
-);
-
--- Indexes
-CREATE INDEX idx_tags_node_id ON tags(node_id);
-CREATE INDEX idx_tags_tag ON tags(tag);
-```
-
-#### `robots`
-
-Robot registry for multi-robot tracking.
-
-```sql
-CREATE TABLE robots (
-  id TEXT PRIMARY KEY,
-  name TEXT NOT NULL,
-  created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
-  last_active TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
-);
-```
-
-#### `operations_log`
-
-Audit log for all operations (hypertable partitioned by `timestamp`).
-
-```sql
-CREATE TABLE operations_log (
-  id SERIAL,
-  operation TEXT NOT NULL,
-  node_id INTEGER REFERENCES nodes(id) ON DELETE SET NULL,
-  robot_id TEXT NOT NULL REFERENCES robots(id),
-  timestamp TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
-  details JSONB
-);
-
--- Indexes
-CREATE INDEX idx_operations_log_timestamp ON operations_log(timestamp DESC);
-CREATE INDEX idx_operations_log_robot_id ON operations_log(robot_id);
-CREATE INDEX idx_operations_log_operation ON operations_log(operation);
-```
-
-### Views
-
-#### `node_stats`
-
-Aggregate statistics by node type.
-
-```sql
-CREATE VIEW node_stats AS
-SELECT
-  type,
-  COUNT(*) as count,
-  AVG(importance) as avg_importance,
-  MIN(created_at) as oldest,
-  MAX(created_at) as newest
-FROM nodes
-GROUP BY type;
-```
-
-#### `robot_activity`
-
-Robot activity summary.
-
-```sql
-CREATE VIEW robot_activity AS
-SELECT
-  id,
-  name,
-  last_active,
-  (SELECT COUNT(*) FROM nodes WHERE robot_id = robots.id) as node_count
-FROM robots
-ORDER BY last_active DESC;
-```
-
----
-
-## TimescaleDB Hypertables
-
-### `nodes` Hypertable
-
-```sql
-SELECT create_hypertable('nodes', 'created_at',
-  if_not_exists => TRUE,
-  migrate_data => TRUE
-);
-```
-
-**Partitioning**: By `created_at` timestamp
-
-**Chunk Interval**: 7 days (default)
-
-**Compression**:
-
-```sql
-ALTER TABLE nodes SET (
-  timescaledb.compress,
-  timescaledb.compress_segmentby = 'robot_id,type'
-);
-
-SELECT add_compression_policy('nodes', INTERVAL '30 days',
-  if_not_exists => TRUE
-);
-```
-
-- Automatically compresses chunks older than 30 days
-- Segments by `robot_id` and `type` for efficient queries
-- Reduces storage by ~90% for old data
-
-### `operations_log` Hypertable
-
-```sql
-SELECT create_hypertable('operations_log', 'timestamp',
-  if_not_exists => TRUE,
-  migrate_data => TRUE
-);
-```
-
-**Partitioning**: By `timestamp`
-
-**Chunk Interval**: 1 day (default)
-
-**Benefits**:
-
-- Fast time-range queries
-- Automatic data retention policies (can be added)
-- Optimized for append-only workload
-
----
-
-## Required PostgreSQL Extensions
-
-### TimescaleDB
-
-Time-series database extension.
-
-```sql
-CREATE EXTENSION IF NOT EXISTS timescaledb;
-```
-
-**Features Used**:
-
-- Hypertables for time-series optimization
-- Automatic chunking and partitioning
-- Compression policies
-- Continuous aggregates (planned)
-
-### pgvector
-
-Vector similarity search.
-
-```sql
-CREATE EXTENSION IF NOT EXISTS vector;
-```
-
-**Features Used**:
-
-- `vector(1536)` data type for embeddings
-- Cosine similarity operator `<=>`
-- IVFFlat index for approximate nearest neighbor
-
-### pg_trgm
-
-Trigram-based text search.
-
-```sql
-CREATE EXTENSION IF NOT EXISTS pg_trgm;
-```
+| Table | Purpose |
+|-------|---------|
+| [robots](../database/public.robots.md) | Robot registry for multi-robot tracking |
+| [nodes](../database/public.nodes.md) | Primary memory storage with vector embeddings |
+| [tags](../database/public.tags.md) | Hierarchical tag names for categorization |
+| [robot_nodes](../database/public.robot_nodes.md) | Robot-to-node associations (hive mind) |
+| [node_tags](../database/public.node_tags.md) | Node-to-tag associations |
+| [working_memories](../database/public.working_memories.md) | Per-robot working memory state |
 
-**Features Used**:
+### Required Extensions
 
-- Full-text search with fuzzy matching
-- GIN indexes for fast text queries
-- Similarity ranking
+| Extension | Purpose |
+|-----------|---------|
+| `pgvector` | Vector similarity search with HNSW indexes |
+| `pg_trgm` | Trigram-based fuzzy text matching |
 
 ---
 
@@ -801,6 +588,7 @@ end
 
 - [HTM API](htm.md) - Main class that uses Database config
 - [LongTermMemory API](long-term-memory.md) - Uses database for storage
-- [Database Schema](../development/schema.md) - Complete schema documentation
-- [TimescaleDB Documentation](https://docs.timescale.com/) - Hypertable features
+- [Database Schema](../development/schema.md) - Query patterns, optimization tips, and best practices
+- [Database Tables](../database/README.md) - Auto-generated table reference with ER diagram
 - [pgvector Documentation](https://github.com/pgvector/pgvector) - Vector search
+- [pg_trgm Documentation](https://www.postgresql.org/docs/current/pgtrgm.html) - Trigram fuzzy matching

data/docs/api/embedding-service.md

@@ -353,13 +353,7 @@ system("ollama pull nomic-embed-text")
 
 ### Exception Types
 
-```ruby
-HTM::EmbeddingError
-  ├─ "Ollama connection failed"
-  ├─ "OpenAI API error: ..."
-  ├─ "Invalid model: ..."
-  └─ "Empty text provided"
-```
+![HTM Exception Hierarchy](../assets/images/exception-hierarchy.svg)
 
 ---