engram-hq-org-knowledge

star 0

Organization knowledge for the Engram platform - a Skill & Memory Browser for AI Agents. Covers architecture, conventions, and cross-repo patterns.

engram-hq By engram-hq schedule Updated 2/12/2026
play_arrow Run Skill in Manus View GitHub

name: engram-hq-org-knowledge description: | Organization knowledge for the Engram platform - a Skill & Memory Browser for AI Agents. Covers architecture, conventions, and cross-repo patterns. last_updated: 2026-02-12

Engram Platform Architecture

Overview

Engram is a multi-tenant SaaS platform that indexes and visualizes AI agent skills and memories stored across GitHub repositories. It provides cost analytics for AI agent operations.

Repositories

  • engram-web: Next.js 16 web application + REST API (primary)
  • .skills: This repository - org-level knowledge base

Tech Stack

  • Framework: Next.js 16 (App Router) + React 19
  • Database: Turso (SQLite via libSQL) + Drizzle ORM
  • Auth: Auth.js v5 with GitHub OAuth + API key auth for agents
  • UI: shadcn/ui + Tailwind v4 + Recharts
  • GitHub Integration: Octokit REST API
  • Markdown: react-markdown v10 + rehype-highlight

Architecture Decisions

Dual Authentication

  • Web users: GitHub OAuth via Auth.js v5 → session cookies
  • AI agents: API keys with eng_ prefix → Bearer token
  • authenticateRequest() checks Bearer first, session fallback

3-Tier Skill Hierarchy

  1. User level (Tier 1): Cross-org skills in user's skills repo
  2. Org level (Tier 2): Org-specific skills in <org>/.skills
  3. Repo level (Tier 3): Project-specific skills in <repo>/.skills/

Database Design

  • 10 tables in Turso (SQLite)
  • Content hashing (SHA-256) for incremental sync
  • Daily rollup tables for fast analytics queries
  • FTS5 virtual tables for full-text search

Agent Metrics

  • POST /v1/metrics/ingest for single/batch event ingestion
  • Server-side cost calculation from model_pricing table
  • Daily rollups via upsert with atomic SQL increments

Conventions

  • All IDs are hex(randomblob(16))
  • API keys: eng_ prefix + 32 random hex bytes, stored as SHA-256 hash
  • Tokens encrypted with AES-256-GCM (IV:authTag:ciphertext format)
  • Content hash: SHA-256 for change detection during sync
  • Memory types: session, cumulative, reference (inferred from path and content)

Known Issues

  • ReactMarkdown v10 removed className prop - wrap in div
  • Edge Runtime can't import Node.js crypto - handle auth in API routes
  • Auth.js v5 profile.id is string|null|undefined - use Number()
Install via CLI
npx skills add https://github.com/engram-hq/.skills --skill engram-hq-org-knowledge
Repository Details
star Stars 0
call_split Forks 0
navigation Branch main
article Path SKILL.md
More from Creator
engram-hq
engram-hq Explore all skills →