@stackmemoryai/stackmemory 1.0.1 → 1.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/src/cli/claude-sm.js +65 -0
- package/dist/src/cli/commands/audit.js +134 -0
- package/dist/src/cli/commands/bench.js +252 -0
- package/dist/src/cli/commands/dashboard.js +2 -1
- package/dist/src/cli/commands/stats.js +118 -0
- package/dist/src/cli/index.js +6 -0
- package/dist/src/core/config/feature-flags.js +7 -1
- package/dist/src/core/context/enhanced-rehydration.js +24 -5
- package/dist/src/core/extensions/cerebras-adapter.js +28 -0
- package/dist/src/core/extensions/deepinfra-adapter.js +32 -0
- package/dist/src/core/extensions/provider-adapter.js +33 -240
- package/dist/src/core/models/complexity-scorer.js +154 -0
- package/dist/src/core/models/model-router.js +230 -36
- package/dist/src/core/models/provider-pricing.js +63 -0
- package/dist/src/core/models/sensitive-guard.js +112 -0
- package/dist/src/core/monitoring/feedback-loops.js +88 -0
- package/dist/src/hooks/schemas.js +12 -1
- package/dist/src/integrations/anthropic/batch-client.js +256 -0
- package/dist/src/integrations/anthropic/client.js +87 -72
- package/dist/src/integrations/claude-code/subagent-client.js +133 -12
- package/dist/src/integrations/graphiti/client.js +16 -4
- package/dist/src/integrations/mcp/handlers/index.js +25 -1
- package/dist/src/integrations/mcp/handlers/provider-handlers.js +227 -0
- package/dist/src/integrations/mcp/server.js +316 -1
- package/dist/src/integrations/mcp/tool-definitions.js +90 -1
- package/dist/src/orchestrators/multimodal/baselines.js +128 -0
- package/dist/src/orchestrators/multimodal/constants.js +9 -1
- package/dist/src/orchestrators/multimodal/harness.js +86 -6
- package/dist/src/orchestrators/multimodal/providers.js +113 -2
- package/dist/src/skills/recursive-agent-orchestrator.js +15 -10
- package/dist/src/utils/fuzzy-edit.js +162 -0
- package/dist/src/utils/hook-installer.js +155 -0
- package/package.json +6 -2
- package/scripts/gepa/.before-optimize.md +159 -0
- package/scripts/gepa/generations/gen-000/baseline.md +159 -124
- package/scripts/gepa/generations/gen-001/baseline.md +159 -0
- package/scripts/gepa/generations/gen-001/variant-a.md +166 -0
- package/scripts/gepa/generations/gen-001/variant-b.md +237 -0
- package/scripts/gepa/generations/gen-001/variant-c.md +61 -0
- package/scripts/gepa/generations/gen-001/variant-d.md +119 -0
- package/scripts/gepa/results/eval-1-baseline.json +41 -0
- package/scripts/gepa/results/eval-1-variant-a.json +41 -0
- package/scripts/gepa/results/eval-1-variant-b.json +41 -0
- package/scripts/gepa/results/eval-1-variant-c.json +41 -0
- package/scripts/gepa/results/eval-1-variant-d.json +41 -0
- package/scripts/gepa/state.json +41 -2
- package/scripts/install-claude-hooks-auto.js +176 -44
- package/templates/claude-hooks/auto-checkpoint.js +174 -0
- package/templates/claude-hooks/chime-on-stop.sh +22 -0
- package/templates/claude-hooks/session-rescue.sh +15 -0
- package/templates/claude-hooks/stop-checkpoint.js +120 -0
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# ProvenantAI
|
|
2
|
+
|
|
3
|
+
## Reference Docs
|
|
4
|
+
```
|
|
5
|
+
AGENTS.md # TDD workflow, checklists, guardrails
|
|
6
|
+
PROMPT_PLAN.md # 20 implementation prompts
|
|
7
|
+
docs/STYLE.md # Design system (Hatchet + Outliner)
|
|
8
|
+
docs/business/ONE_PAGER.md # Executive summary
|
|
9
|
+
DEV_SPEC.md # Developer spec
|
|
10
|
+
docs/reference/PROJECT.md # Quick reference
|
|
11
|
+
docs/business/VISION.md # Product vision + self-learning + model router
|
|
12
|
+
docs/architecture/SYSTEM_INTEGRATION.md # System connections (events, flows)
|
|
13
|
+
docs/architecture/HEARTBEAT_DESIGN.md # Task health + recovery
|
|
14
|
+
docs/nudge-engine-design.md # Proactive scanner alerts
|
|
15
|
+
docs/architecture/WEBHOOK_SYSTEM_DESIGN.md # External event publishing
|
|
16
|
+
docs/VALUES.md # Company values
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Commands
|
|
20
|
+
```bash
|
|
21
|
+
npm run dev|test|lint|migrate # Development tasks
|
|
22
|
+
docker-compose up -d # Start local DBs
|
|
23
|
+
railway up # Deploy to Railway
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Stack
|
|
27
|
+
Node.js + Express + PostgreSQL + Redis | Railway | Stripe + Salesforce + QuickBooks
|
|
28
|
+
|
|
29
|
+
## Core Services (src/core/)
|
|
30
|
+
monitoring-service | cache-service | queue-service | master-agent | api-validation
|
|
31
|
+
|
|
32
|
+
## Directory Structure
|
|
33
|
+
```
|
|
34
|
+
src/
|
|
35
|
+
api/ core/ features/ shared/ integrations/
|
|
36
|
+
docs/ scripts/ docker/
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Git Workflow
|
|
40
|
+
- **NEVER add Co-Authored-By lines** to commits
|
|
41
|
+
- Pre-commit: runs lint + test suite
|
|
42
|
+
- Commit format: `type(scope): message`
|
|
43
|
+
- Deploy: `railway up --detach`
|
|
44
|
+
|
|
45
|
+
## Architecture
|
|
46
|
+
- **Provenance tracking**: every data point includes source + timestamp + lineage
|
|
47
|
+
- **Multi-tenant**: container isolation per org
|
|
48
|
+
- **Investigation replays**: stored in `data/investigation-replays/`
|
|
49
|
+
- **StackMemory**: session/entity context layer (repurpose when KG lands)
|
|
50
|
+
|
|
51
|
+
## Key Implementation Files
|
|
52
|
+
```
|
|
53
|
+
src/graph/client.ts # MCP client for Graphiti
|
|
54
|
+
src/graph/service.ts # Graph ingest + enrich + search
|
|
55
|
+
src/llm/adapter.js # LLM streaming + SYSTEM_PROMPT
|
|
56
|
+
src/routes/query.js # Query endpoint + KG enrichment
|
|
57
|
+
src/auth/auth.middleware.js # Clerk + API key + test mode
|
|
58
|
+
src/nudge/rule-engine.js # 13 default rules + CRUD + eval
|
|
59
|
+
src/nudge/nudge-engine.js # Lifecycle + state machine + events
|
|
60
|
+
src/nudge/delivery.js # Slack Block Kit + delivery
|
|
61
|
+
src/integrations/slack/app.js # OAuth v2 + token management
|
|
62
|
+
scripts/create-stripe-products.js # Stripe product creation
|
|
63
|
+
scripts/seed-demo-data.js # Demo nudge data
|
|
64
|
+
dashboard-app/src/pages/pricing/ # 4-tier pricing UI
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Current State
|
|
68
|
+
- **20 prompts complete** (PROMPT_PLAN.md)
|
|
69
|
+
- **80 test suites, 1547 tests** - all passing (37 unit, 30 core, 13 integrations)
|
|
70
|
+
- **KG integrated** - commit 917f31e (FalkorDB + Graphiti MCP)
|
|
71
|
+
- **Published**: @provenantai/cli@1.0.0
|
|
72
|
+
- **Deployed**: Railway (health OK, DB connected)
|
|
73
|
+
- **Bundle**: 236KB main + 346KB vendor (lazy routes)
|
|
74
|
+
- **Pricing**: Free | Growth $999-1499 | Scale $2999-4499 | Enterprise custom
|
|
75
|
+
- **Slack**: wired in index.js (conditional on SLACK_CLIENT_ID)
|
|
76
|
+
- **Dashboard**: SlackSettings + Nudges page + E2E smoke tests
|
|
77
|
+
|
|
78
|
+
## Knowledge Graph
|
|
79
|
+
- **FalkorDB**: `falkordb/falkordb:latest` port 6380 (Redis-compatible)
|
|
80
|
+
- **Graphiti**: `zepai/knowledge-graph-mcp:standalone` port 8100
|
|
81
|
+
- **Protocol**: MCP Streamable HTTP (JSON-RPC + SSE) - NOT REST
|
|
82
|
+
- **Ingestion**: fire-and-forget via `add_memory`, extraction runs in background
|
|
83
|
+
- **Config**: `config/graphiti-falkordb.yaml` - Claude Haiku for LLM
|
|
84
|
+
- **Performance**: 34ms avg, $0.00056/event
|
|
85
|
+
- **Query integration**: GraphService.enrichRetrieval() when GRAPHITI_URL set
|
|
86
|
+
- **Graph context**: prepended as first context_document, graceful fallback
|
|
87
|
+
|
|
88
|
+
## Stripe Products (LIVE)
|
|
89
|
+
```
|
|
90
|
+
Growth: prod_TyNYCJmlKbMdlz
|
|
91
|
+
Monthly $1,499: price_1T0Qn8BjaxUVbh5VjC7BP0cS
|
|
92
|
+
Quarterly $2,997: price_1T0Qn9BjaxUVbh5VYmugdPrF
|
|
93
|
+
Scale: prod_TyNY5SGKvVlbpo
|
|
94
|
+
Monthly $4,499: price_1T0Qn9BjaxUVbh5ViK6vRmgn
|
|
95
|
+
Quarterly $8,997: price_1T0Qn9BjaxUVbh5V1mBcTAJ0
|
|
96
|
+
```
|
|
97
|
+
Price IDs in `.env` + `dashboard-app/.env` (VITE_STRIPE_PRICE_*)
|
|
98
|
+
|
|
99
|
+
## Clerk Auth
|
|
100
|
+
- **Current**: test keys (pk_test_*, sk_test_*)
|
|
101
|
+
- **Production setup**: `bash scripts/setup-clerk-production.sh`
|
|
102
|
+
- **Webhook**: /api/webhooks/clerk (Svix verification required in prod)
|
|
103
|
+
- **Status**: code production-ready, test mode blocked in production
|
|
104
|
+
|
|
105
|
+
## Dashboard
|
|
106
|
+
- **Chat**: `/api/v1/query` with SSE streaming
|
|
107
|
+
- **Sidebar**: toggleable, time-grouped, backend persistence
|
|
108
|
+
- **localStorage**: `provenantai:conversationId`, `sidebarOpen`, `onboarded`
|
|
109
|
+
- **Vite**: `base: '/app/'` + BrowserRouter `basename="/app"`
|
|
110
|
+
- **Dev auth**: `X-Test-Mode: true` bypasses Clerk
|
|
111
|
+
- **Express**: `node src/index.js` on PORT=8080 (3000 = Rails)
|
|
112
|
+
- **Build**: `bash -c 'cd dashboard-app && npx vite build'`
|
|
113
|
+
|
|
114
|
+
## Slack Integration
|
|
115
|
+
- **OAuth flow**: GET /api/integrations/slack/install → consent → callback
|
|
116
|
+
- **DB**: `slack_installations` table (migration 030) - per-org bot tokens
|
|
117
|
+
- **Service**: `src/integrations/slack/app.js` - createSlackAppService
|
|
118
|
+
- **Delivery**: `src/nudge/delivery.js` - nudge:created listener, Block Kit formatter
|
|
119
|
+
- **Routes**: install, callback, status, channel config, revoke
|
|
120
|
+
- **Env**: SLACK_CLIENT_ID, SLACK_CLIENT_SECRET, SLACK_REDIRECT_URI
|
|
121
|
+
- **Demo data**: `node scripts/seed-demo-data.js` (10 nudges)
|
|
122
|
+
|
|
123
|
+
## Architecture Patterns
|
|
124
|
+
- **DI**: all route factories accept `deps` objects
|
|
125
|
+
- **Mocks**: MockPineconeAdapter, MockGmailConnectorClient, stub embeddings
|
|
126
|
+
- **Queues**: Bull (not BullMQ)
|
|
127
|
+
- **KMS**: AES-256-GCM shim via LOCAL_KMS_KEY
|
|
128
|
+
- **Streaming**: adapter.streamLLM() → query/stream → ReadableStream
|
|
129
|
+
- **Graph**: optional graphService dep, null when GRAPHITI_URL unset
|
|
130
|
+
|
|
131
|
+
## Testing
|
|
132
|
+
- **Framework**: Jest + SWC (`@swc/jest`), `@jest/globals` imports
|
|
133
|
+
- **Mocks**: `mockDb = { query: jest.fn() }` via DI
|
|
134
|
+
- **Fetch**: `global.fetch = mockFetch` + `jsonResponse()` helper
|
|
135
|
+
- **Pre-commit**: lint + parallel test suite via concurrently
|
|
136
|
+
- **Timeout guard**: Promise.race + .unref() timer in test/setup.js
|
|
137
|
+
- **Supertest**: pass Express app directly (NOT server) - avoids port contention
|
|
138
|
+
- **Redis**: skip eager connect in NODE_ENV=test; disconnect in afterAll
|
|
139
|
+
|
|
140
|
+
### Parallel Test Execution
|
|
141
|
+
```bash
|
|
142
|
+
npm test # 3 parallel processes (~9s vs 18s)
|
|
143
|
+
test:unit (37 suites, 615 tests) # test/ dir
|
|
144
|
+
test:core (30 suites, 643 tests) # src/(api|auth|billing|core|...)
|
|
145
|
+
test:integrations (13 suites, 289 tests) # src/integrations/
|
|
146
|
+
test:all (single-process, 4 workers) # fallback
|
|
147
|
+
```
|
|
148
|
+
**After code changes**: run targeted sub-suite in background via Bash `run_in_background`
|
|
149
|
+
|
|
150
|
+
## GTM Content
|
|
151
|
+
```
|
|
152
|
+
docs/content/linkedin-pillar1-drafts.md # 5 problem posts (ready)
|
|
153
|
+
docs/content/gtm-launch-materials.md # Schedule + Loom + outreach
|
|
154
|
+
docs/business/CONTENT_INBOUND_STRATEGY.md # Content/inbound playbook
|
|
155
|
+
docs/business/FRACTIONAL_CMO_AGENT.md # CMO Agent product brief
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## Next Actions
|
|
159
|
+
1. Commit: SlackSettings, Nudges polish, smoke tests
|
|
160
|
+
2. Clerk: swap to production keys (requires Clerk dashboard action)
|
|
161
|
+
3. Slack: create app at api.slack.com, run migration 030
|
|
162
|
+
4. Content: schedule posts in Typefully, record Loom demo
|
|
163
|
+
5. Design partners: outreach to 3-5 ICP companies
|
|
164
|
+
6. Attribution: add Google Ads + Meta connectors
|
|
165
|
+
|
|
166
|
+
<!-- Sync docs/reference/PROJECT.md when verbose docs change -->
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
# CLAUDE.md [compact]
|
|
2
|
+
|
|
3
|
+
## Refs
|
|
4
|
+
```
|
|
5
|
+
~/.claude/MCP.md|PERSONAS.md|STACKMEMORY.md
|
|
6
|
+
~/.claude/agent_docs/*.compact.md (on-demand)
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## Commands
|
|
10
|
+
```
|
|
11
|
+
build|lint|lint:fix|test|test:run
|
|
12
|
+
git status|diff|log --oneline -10
|
|
13
|
+
npx tsc --noEmit|npm run format
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Core
|
|
17
|
+
[PRINCIPLE]code>docs|simple→complex|security first|evidence-based
|
|
18
|
+
[COMM]concise|symbols>prose|bullets>paragraphs|<4 lines
|
|
19
|
+
[WORKFLOW]TodoWrite(3+)→execute→update
|
|
20
|
+
[GIT]clean commits|type(scope): message|feature/|fix/|chore/ prefix
|
|
21
|
+
[STACK]React/TS/Vite|Node/Express/PG|Git/ESLint/Jest
|
|
22
|
+
|
|
23
|
+
## Think
|
|
24
|
+
[NONE]single file,<10 lines
|
|
25
|
+
[THINK]multi-file,standard|~4K
|
|
26
|
+
[HARD]architecture,complex|~10K
|
|
27
|
+
[ULTRA]critical redesign|~32K
|
|
28
|
+
|
|
29
|
+
## Critical [C:10]
|
|
30
|
+
[SECURITY]
|
|
31
|
+
NEVER:commit secrets|exec untrusted|expose PII|force push
|
|
32
|
+
ALWAYS:validate input|parameterized queries|hash passwords
|
|
33
|
+
BLOCK:~/.ssh|~/.aws|/api[_-]?key|token|secret/i
|
|
34
|
+
|
|
35
|
+
<example>
|
|
36
|
+
❌ BAD:
|
|
37
|
+
```js
|
|
38
|
+
db.query(`SELECT * FROM users WHERE id = ${userId}`)
|
|
39
|
+
```
|
|
40
|
+
✅ GOOD:
|
|
41
|
+
```js
|
|
42
|
+
db.query('SELECT * FROM users WHERE id = $1', [userId])
|
|
43
|
+
```
|
|
44
|
+
</example>
|
|
45
|
+
|
|
46
|
+
[ESM]add .js to relative imports|use ts-node-lint-fixer agent on ERR_MODULE_NOT_FOUND
|
|
47
|
+
|
|
48
|
+
<example>
|
|
49
|
+
❌ BAD:
|
|
50
|
+
```ts
|
|
51
|
+
import { foo } from './bar'
|
|
52
|
+
```
|
|
53
|
+
✅ GOOD:
|
|
54
|
+
```ts
|
|
55
|
+
import { foo } from './bar.js'
|
|
56
|
+
```
|
|
57
|
+
</example>
|
|
58
|
+
|
|
59
|
+
[ERROR]return undefined>throw|log+continue>crash|filter nulls
|
|
60
|
+
|
|
61
|
+
<example>
|
|
62
|
+
❌ BAD:
|
|
63
|
+
```js
|
|
64
|
+
function getUser(id) {
|
|
65
|
+
if (!id) throw new Error('No ID')
|
|
66
|
+
return users.find(u => u.id === id)
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
✅ GOOD:
|
|
70
|
+
```js
|
|
71
|
+
function getUser(id) {
|
|
72
|
+
if (!id) return undefined
|
|
73
|
+
return users.find(u => u.id === id)
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
</example>
|
|
77
|
+
|
|
78
|
+
[CODE]no emojis|comments only complex logic|short names
|
|
79
|
+
|
|
80
|
+
<example>
|
|
81
|
+
❌ BAD:
|
|
82
|
+
```js
|
|
83
|
+
// This function gets the user from the database
|
|
84
|
+
function getUserFromDatabase(userId) { ... }
|
|
85
|
+
```
|
|
86
|
+
✅ GOOD:
|
|
87
|
+
```js
|
|
88
|
+
function getUser(id) { ... }
|
|
89
|
+
// Only comment complex parts:
|
|
90
|
+
const hash = await bcrypt.hash(pwd, 10) // 10 rounds for security/perf balance
|
|
91
|
+
```
|
|
92
|
+
</example>
|
|
93
|
+
|
|
94
|
+
## High [H:8-9]
|
|
95
|
+
[EFFICIENCY]do>explain|action>ceremony|parallel>sequential
|
|
96
|
+
|
|
97
|
+
<example>
|
|
98
|
+
❌ BAD: "I'll read file A, then file B, then file C..."
|
|
99
|
+
✅ GOOD: [Read A, Read B, Read C in parallel]
|
|
100
|
+
</example>
|
|
101
|
+
|
|
102
|
+
[GIT]status→branch→fetch→pull --rebase|type(scope): message
|
|
103
|
+
|
|
104
|
+
<example>
|
|
105
|
+
✅ GOOD commit messages:
|
|
106
|
+
- feat(auth): add JWT token refresh
|
|
107
|
+
- fix(api): handle null responses
|
|
108
|
+
- chore(deps): bump express to 4.18
|
|
109
|
+
</example>
|
|
110
|
+
|
|
111
|
+
[RECOVERY]try alt→explain→suggest next|never silent fail
|
|
112
|
+
|
|
113
|
+
<example>
|
|
114
|
+
❌ BAD: Test fails → retry same command → retry again
|
|
115
|
+
✅ GOOD: Test fails → check logs → try different approach → explain issue
|
|
116
|
+
</example>
|
|
117
|
+
|
|
118
|
+
[SESSION]track edits/corrections/paths|cache versions/locations
|
|
119
|
+
|
|
120
|
+
## Standards
|
|
121
|
+
[TASK]TodoWrite 3+|one in_progress|update immediate
|
|
122
|
+
|
|
123
|
+
<example>
|
|
124
|
+
✅ GOOD workflow:
|
|
125
|
+
1. User asks to add feature
|
|
126
|
+
2. TodoWrite: ["Design API", "Implement handler", "Add tests", "Update docs"]
|
|
127
|
+
3. TaskUpdate task1 → in_progress
|
|
128
|
+
4. Complete work
|
|
129
|
+
5. TaskUpdate task1 → completed
|
|
130
|
+
6. TaskUpdate task2 → in_progress
|
|
131
|
+
</example>
|
|
132
|
+
|
|
133
|
+
[DESIGN]KISS|YAGNI|SOLID|<20 lines/fn|<5 complexity
|
|
134
|
+
|
|
135
|
+
<example>
|
|
136
|
+
❌ BAD:
|
|
137
|
+
```js
|
|
138
|
+
function processUserDataWithValidationAndTransformation(user, options) {
|
|
139
|
+
// 50 lines of mixed concerns
|
|
140
|
+
}
|
|
141
|
+
```
|
|
142
|
+
✅ GOOD:
|
|
143
|
+
```js
|
|
144
|
+
function validateUser(user) { ... } // 8 lines
|
|
145
|
+
function transformUser(user) { ... } // 6 lines
|
|
146
|
+
function processUser(user) { // 3 lines
|
|
147
|
+
const valid = validateUser(user)
|
|
148
|
+
return valid ? transformUser(user) : null
|
|
149
|
+
}
|
|
150
|
+
```
|
|
151
|
+
</example>
|
|
152
|
+
|
|
153
|
+
[FILES]read before write|edit>write|no docs unless asked
|
|
154
|
+
|
|
155
|
+
<example>
|
|
156
|
+
❌ BAD: User asks to update function → Write entire new file
|
|
157
|
+
✅ GOOD: User asks to update function → Read file → Edit specific function
|
|
158
|
+
</example>
|
|
159
|
+
|
|
160
|
+
[VALIDATE]lint→test→build→run|never assume success
|
|
161
|
+
|
|
162
|
+
<example>
|
|
163
|
+
✅ GOOD workflow:
|
|
164
|
+
1. Edit code
|
|
165
|
+
2. `npm run lint` → check output
|
|
166
|
+
3. `npm test` → verify passing
|
|
167
|
+
4. `npm run build` → ensure clean build
|
|
168
|
+
5. Only then mark task complete
|
|
169
|
+
</example>
|
|
170
|
+
|
|
171
|
+
[COVERAGE]maintain or improve test coverage|no untested code paths
|
|
172
|
+
|
|
173
|
+
<example>
|
|
174
|
+
❌ BAD: Add new route without tests
|
|
175
|
+
✅ GOOD: Add new route + unit test + integration test
|
|
176
|
+
</example>
|
|
177
|
+
|
|
178
|
+
## Style
|
|
179
|
+
[OUTPUT]concise|structured|actionable
|
|
180
|
+
|
|
181
|
+
<example>
|
|
182
|
+
❌ BAD: "I've made some changes to the authentication system to improve security..."
|
|
183
|
+
✅ GOOD: "Added JWT refresh tokens in src/auth/tokens.js:45"
|
|
184
|
+
</example>
|
|
185
|
+
|
|
186
|
+
[PUSHBACK]"Simpler: X"|"Risk: Y"|"Consider: Z"
|
|
187
|
+
|
|
188
|
+
<example>
|
|
189
|
+
User: "Add Redis caching to all endpoints"
|
|
190
|
+
✅ GOOD response: "Risk: premature optimization. Consider: profile first, cache hot paths only"
|
|
191
|
+
</example>
|
|
192
|
+
|
|
193
|
+
[QUESTIONS]1-3 clarifying|one at a time|no time estimates
|
|
194
|
+
|
|
195
|
+
<example>
|
|
196
|
+
❌ BAD: "This will take 2-3 hours. Should I add error handling, logging, tests, docs, and type safety?"
|
|
197
|
+
✅ GOOD: "Add error handling for network failures?"
|
|
198
|
+
</example>
|
|
199
|
+
|
|
200
|
+
## Summary Format
|
|
201
|
+
```
|
|
202
|
+
Session: actual vs estimated|variance %
|
|
203
|
+
Completed: N/M tasks|files modified|commits
|
|
204
|
+
Outcomes: deliverables|blockers|next actions
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
<example>
|
|
208
|
+
✅ GOOD summary:
|
|
209
|
+
```
|
|
210
|
+
Completed: 3/4 tasks | 7 files | 2 commits
|
|
211
|
+
Outcomes: Auth refresh implemented, tests passing
|
|
212
|
+
Blockers: Redis connection requires env var
|
|
213
|
+
Next: Add REDIS_URL to .env, deploy to staging
|
|
214
|
+
```
|
|
215
|
+
</example>
|
|
216
|
+
|
|
217
|
+
## Auto-Activate
|
|
218
|
+
[FILES]*.tsx→frontend|*.sql→data|Docker→devops|*.test→qa
|
|
219
|
+
[KEYWORDS]bug/error→debugger|optimize→perf|secure→security
|
|
220
|
+
|
|
221
|
+
<example>
|
|
222
|
+
User shares error.tsx → automatically apply frontend patterns
|
|
223
|
+
User mentions "slow query" → automatically consider performance context
|
|
224
|
+
</example>
|
|
225
|
+
|
|
226
|
+
## Expand (read on match)
|
|
227
|
+
[AGENTIC]multi-agent→AGENTIC_CODING.compact.md
|
|
228
|
+
[CONTEXT]token budget→CONTEXT_MANAGEMENT.compact.md
|
|
229
|
+
[TOOLS]parallel tools→TOOL_USE.compact.md
|
|
230
|
+
[HORIZON]multi-session→LONG_HORIZON.compact.md
|
|
231
|
+
[PROMPTS]prompt design→PROMPT_ENGINEERING.compact.md
|
|
232
|
+
[BUILD]npm build|esbuild|tsc→building_the_project.md
|
|
233
|
+
[CODE]conventions|naming|imports→code_conventions.md
|
|
234
|
+
[TEST]vitest|jest|test:run→running_tests.md
|
|
235
|
+
[OVERVIEW]agent docs|guides→OVERVIEW.md
|
|
236
|
+
|
|
237
|
+
~150t|v4.4.0-compact
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# ProvenantAI
|
|
2
|
+
|
|
3
|
+
## Refs
|
|
4
|
+
```
|
|
5
|
+
AGENTS.md # Agent workflow + guardrails
|
|
6
|
+
PROMPT_PLAN.md # 20 staged prompts
|
|
7
|
+
docs/STYLE.md # Design system (Hatchet + Outliner)
|
|
8
|
+
docs/business/ONE_PAGER.md|VISION.md # Executive summary + vision
|
|
9
|
+
DEV_SPEC.md # Developer spec
|
|
10
|
+
docs/reference/PROJECT.md # Quick reference
|
|
11
|
+
docs/architecture/SYSTEM_INTEGRATION.md # System connections
|
|
12
|
+
docs/architecture/HEARTBEAT_DESIGN.md|WEBHOOK_SYSTEM_DESIGN.md
|
|
13
|
+
docs/nudge-engine-design.md # Proactive alerts
|
|
14
|
+
docs/VALUES.md # Company values
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Commands
|
|
18
|
+
```bash
|
|
19
|
+
npm run dev|test|lint|migrate
|
|
20
|
+
docker-compose up -d; railway up # Local DBs; Deploy
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Stack
|
|
24
|
+
Node/Express/PostgreSQL/Redis | Railway | Stripe/Salesforce/QuickBooks
|
|
25
|
+
|
|
26
|
+
## Structure
|
|
27
|
+
src/api|core|features|shared|integrations | docs/ | scripts/ | docker/
|
|
28
|
+
|
|
29
|
+
## Key Context
|
|
30
|
+
- Provenance tracking: source + timestamp + lineage on all data
|
|
31
|
+
- Multi-tenant container isolation
|
|
32
|
+
- Investigation replays: data/investigation-replays/
|
|
33
|
+
- StackMemory: security layer (future session/entity context bridge on KG)
|
|
34
|
+
|
|
35
|
+
## Git
|
|
36
|
+
- No "Co-Authored-By" lines
|
|
37
|
+
- Pre-commit: lint + test (3 parallel suites: unit/core/integrations)
|
|
38
|
+
- Commit format: type(scope): message
|
|
39
|
+
|
|
40
|
+
## Critical Rules
|
|
41
|
+
[SECURITY]
|
|
42
|
+
NEVER: commit secrets|exec untrusted|expose PII|force push
|
|
43
|
+
ALWAYS: validate input|parameterized queries|hash passwords
|
|
44
|
+
BLOCK: ~/.ssh|~/.aws|/api[_-]?key|token|secret/i
|
|
45
|
+
|
|
46
|
+
[ESM] Add .js to relative imports | use ts-node-lint-fixer on ERR_MODULE_NOT_FOUND
|
|
47
|
+
[ERROR] return undefined>throw | log+continue>crash | filter nulls
|
|
48
|
+
[CODE] no emojis | comments only complex logic | short names
|
|
49
|
+
|
|
50
|
+
## Workflow
|
|
51
|
+
[EFFICIENCY] do>explain | action>ceremony | parallel>sequential
|
|
52
|
+
[TASK] TodoWrite 3+ | one in_progress | update immediate
|
|
53
|
+
[DESIGN] KISS|YAGNI|SOLID | <20 lines/fn | <5 complexity
|
|
54
|
+
[FILES] read before write | edit>write | no docs unless asked
|
|
55
|
+
[VALIDATE] lint→test→build→run | never assume success
|
|
56
|
+
[COVERAGE] maintain or improve | no untested paths
|
|
57
|
+
|
|
58
|
+
## Style
|
|
59
|
+
[OUTPUT] concise | structured | actionable | <4 lines default
|
|
60
|
+
[PUSHBACK] "Simpler: X" | "Risk: Y" | "Consider: Z"
|
|
61
|
+
[QUESTIONS] 1-3 clarifying | one at a time | no time estimates
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# ProvenantAI — CLAUDE.md
|
|
2
|
+
|
|
3
|
+
## Quick Reference
|
|
4
|
+
```
|
|
5
|
+
AGENTS.md # TDD workflow, checklists, guardrails
|
|
6
|
+
docs/STYLE.md # Design system (Hatchet + Outliner)
|
|
7
|
+
docs/business/ONE_PAGER.md # Executive summary
|
|
8
|
+
docs/business/VISION.md # Product vision + self-learning thesis
|
|
9
|
+
DEV_SPEC.md|PROMPT_PLAN.md # Dev spec + 20 staged prompts
|
|
10
|
+
docs/architecture/{SYSTEM_INTEGRATION,HEARTBEAT_DESIGN,WEBHOOK_SYSTEM_DESIGN}.md
|
|
11
|
+
docs/nudge-engine-design.md # Proactive alerts
|
|
12
|
+
docs/VALUES.md # Company values
|
|
13
|
+
docs/reference/PROJECT.md # Quick reference (sync with verbose docs)
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Stack & Commands
|
|
17
|
+
```bash
|
|
18
|
+
# Stack: Node/Express/PostgreSQL/Redis | Railway | Stripe/Salesforce/QuickBooks
|
|
19
|
+
npm run dev|test|lint|migrate
|
|
20
|
+
docker-compose up -d # Local DBs
|
|
21
|
+
railway up --detach # Deploy
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Core Principles [C:10]
|
|
25
|
+
**Code First**: code>docs | simple→complex | action>explanation | do>plan
|
|
26
|
+
**Security**: NEVER commit secrets|exec untrusted|expose PII|force push
|
|
27
|
+
ALWAYS validate input|parameterized queries|hash passwords
|
|
28
|
+
BLOCK ~/.ssh|~/.aws|/api[_-]?key|token|secret/i
|
|
29
|
+
**ESM**: add .js to relative imports | use ts-node-lint-fixer on ERR_MODULE_NOT_FOUND
|
|
30
|
+
**Reliability**: return undefined>throw | log+continue>crash | filter nulls
|
|
31
|
+
**Style**: no emojis | comments only for complex logic | short names | concise output
|
|
32
|
+
|
|
33
|
+
## Workflow [H:8-9]
|
|
34
|
+
**Tasks**: TodoWrite for 3+ steps | one in_progress | update immediately
|
|
35
|
+
**Files**: read before write | edit>write | no docs unless asked
|
|
36
|
+
**Git**: status→branch→fetch→pull --rebase | clean commits | type(scope): message
|
|
37
|
+
Branches: feature/|fix/|chore/ prefix
|
|
38
|
+
NO Co-Authored-By lines
|
|
39
|
+
**Validate**: lint→test→build→run | never assume success | maintain test coverage
|
|
40
|
+
**Parallel**: independent tool calls in one message | sequential only for dependencies
|
|
41
|
+
**Recovery**: try alt→explain→suggest | never silent fail
|
|
42
|
+
|
|
43
|
+
## Architecture
|
|
44
|
+
**Core** (src/core/): monitoring-service|cache-service|queue-service|master-agent|api-validation
|
|
45
|
+
**Structure**: src/{api,core,features,shared,integrations} | docs/ | scripts/ | docker/
|
|
46
|
+
**Patterns**: DI via deps objects | Mock providers in tests | Bull queues | AES-256-GCM KMS
|
|
47
|
+
**Provenance**: every data point = source + timestamp + lineage | multi-tenant isolation
|
|
48
|
+
**SSE**: adapter.streamLLM() → query/stream → frontend ReadableStream
|
|
49
|
+
**Graph**: optional graphService in query router (null when GRAPHITI_URL unset)
|
|
50
|
+
|
|
51
|
+
## Standards [H:8]
|
|
52
|
+
**Design**: KISS|YAGNI|SOLID | <20 lines/fn | <5 complexity
|
|
53
|
+
**Testing**: Jest+SWC | @jest/globals imports | DB/fetch mocks via DI
|
|
54
|
+
Supertest: pass Express app (NOT server)
|
|
55
|
+
Redis: skip connect in NODE_ENV=test
|
|
56
|
+
afterAll: Promise.race + .unref() timer
|
|
57
|
+
Parallel suites: test:unit|test:core|test:integrations (~9s vs 18s)
|
|
58
|
+
**After code changes**: run targeted sub-suite in background
|
|
59
|
+
**Coverage**: maintain or improve | no untested paths
|
|
60
|
+
|
|
61
|
+
## Key Context
|
|
62
|
+
- All 20 PROMPT_PLAN.md prompts complete | 80 suites, 1547 tests passing
|
|
63
|
+
- KG: FalkorDB port 6380 + Graphiti MCP port 8100 | MCP protocol (not REST)
|
|
64
|
+
- @provenantai/cli@1.0.0 published | Railway deployed | Bundle: 236KB+346KB
|
|
65
|
+
- Stripe: Growth (prod_TyNYCJmlKbMdlz) $1499/mo | Scale (prod_TyNY5SGKvVlbpo) $4499/mo
|
|
66
|
+
- Clerk: test keys active | production validator: scripts/setup-clerk-production.sh
|
|
67
|
+
- Dashboard: /app/ base | SSE to /api/v1/query | Sidebar in localStorage
|
|
68
|
+
- Slack: OAuth v2 (migration 030) | delivery.js listens nudge:created | demo: seed-demo-data.js
|
|
69
|
+
|
|
70
|
+
## Key Files
|
|
71
|
+
```
|
|
72
|
+
src/graph/{client.ts,service.ts} # MCP client + graph logic
|
|
73
|
+
src/llm/adapter.js # SYSTEM_PROMPT + streaming
|
|
74
|
+
src/routes/query.js # Query + KG enrichment
|
|
75
|
+
src/auth/auth.middleware.js # Clerk + API key + test mode
|
|
76
|
+
src/nudge/{rule-engine,nudge-engine,delivery}.js # Rules + lifecycle + Slack
|
|
77
|
+
src/integrations/slack/app.js # OAuth v2 + token mgmt
|
|
78
|
+
scripts/{create-stripe-products,seed-demo-data}.js
|
|
79
|
+
dashboard-app/src/pages/{pricing/PricingPage,checkout/*}.tsx
|
|
80
|
+
docs/content/{linkedin-pillar1-drafts,gtm-launch-materials}.md
|
|
81
|
+
docs/business/{CONTENT_INBOUND_STRATEGY,FRACTIONAL_CMO_AGENT}.md
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Design System (docs/STYLE.md)
|
|
85
|
+
- Layout: 208px sidebar | inset shadow main | shadow-soft variants
|
|
86
|
+
- Type: 10-24px (no text-lg+ in app) | tabular-nums | Inter/SF Mono | font-mono headers
|
|
87
|
+
- Color: slate/zinc | brand-600 blue | rose accent CTAs
|
|
88
|
+
- Anti-patterns: no @apply sprawl | no inline hex | no shadow-md+ | max rounded-xl
|
|
89
|
+
|
|
90
|
+
## Output Format
|
|
91
|
+
**Session Summary**:
|
|
92
|
+
```
|
|
93
|
+
Actual vs estimated | variance %
|
|
94
|
+
Completed: N/M tasks | files modified | commits
|
|
95
|
+
Deliverables | blockers | next actions
|
|
96
|
+
```
|
|
97
|
+
**Communication**: concise | bullets>paragraphs | <4 lines | structured
|
|
98
|
+
**Pushback**: "Simpler: X" | "Risk: Y" | "Consider: Z"
|
|
99
|
+
**Questions**: 1-3 max | one at a time | no time estimates
|
|
100
|
+
|
|
101
|
+
## Token Budget (Think Mode)
|
|
102
|
+
[NONE] single file, <10 lines
|
|
103
|
+
[THINK] multi-file, standard | ~4K
|
|
104
|
+
[HARD] architecture, complex | ~10K
|
|
105
|
+
[ULTRA] critical redesign | ~32K
|
|
106
|
+
|
|
107
|
+
## Auto-Activate
|
|
108
|
+
[FILES] *.tsx→frontend | *.sql→data | Docker→devops | *.test→qa
|
|
109
|
+
[KEYWORDS] bug/error→debugger | optimize→perf | secure→security
|
|
110
|
+
|
|
111
|
+
## Next Priorities (Memory)
|
|
112
|
+
- Commit uncommitted agent work (SlackSettings, Nudges polish, smoke tests)
|
|
113
|
+
- Clerk: swap to production keys (user action in dashboard)
|
|
114
|
+
- Slack: create app at api.slack.com, run migration 030
|
|
115
|
+
- Content: schedule pillar posts in Typefully, record Loom demo
|
|
116
|
+
- Design partners: outreach to 3-5 ICP companies
|
|
117
|
+
- Ad platform connectors: Google Ads / Meta for attribution story
|
|
118
|
+
|
|
119
|
+
<!-- Update docs/reference/PROJECT.md when verbose docs change -->
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
{
|
|
2
|
+
"variant": "baseline",
|
|
3
|
+
"generation": 1,
|
|
4
|
+
"results": [
|
|
5
|
+
{
|
|
6
|
+
"taskId": "eval-001",
|
|
7
|
+
"taskName": "simple_function",
|
|
8
|
+
"passed": false,
|
|
9
|
+
"duration": 6,
|
|
10
|
+
"output": "/bin/sh: timeout: command not found\n"
|
|
11
|
+
},
|
|
12
|
+
{
|
|
13
|
+
"taskId": "eval-002",
|
|
14
|
+
"taskName": "refactor_code",
|
|
15
|
+
"passed": false,
|
|
16
|
+
"duration": 5,
|
|
17
|
+
"output": "/bin/sh: timeout: command not found\n"
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
"taskId": "eval-003",
|
|
21
|
+
"taskName": "fix_bug",
|
|
22
|
+
"passed": false,
|
|
23
|
+
"duration": 5,
|
|
24
|
+
"output": "/bin/sh: timeout: command not found\n"
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"taskId": "eval-004",
|
|
28
|
+
"taskName": "add_feature",
|
|
29
|
+
"passed": false,
|
|
30
|
+
"duration": 5,
|
|
31
|
+
"output": "/bin/sh: timeout: command not found\n"
|
|
32
|
+
},
|
|
33
|
+
{
|
|
34
|
+
"taskId": "eval-005",
|
|
35
|
+
"taskName": "code_review",
|
|
36
|
+
"passed": false,
|
|
37
|
+
"duration": 4,
|
|
38
|
+
"output": "/bin/sh: timeout: command not found\n"
|
|
39
|
+
}
|
|
40
|
+
]
|
|
41
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
{
|
|
2
|
+
"variant": "variant-a",
|
|
3
|
+
"generation": 1,
|
|
4
|
+
"results": [
|
|
5
|
+
{
|
|
6
|
+
"taskId": "eval-001",
|
|
7
|
+
"taskName": "simple_function",
|
|
8
|
+
"passed": false,
|
|
9
|
+
"duration": 5,
|
|
10
|
+
"output": "/bin/sh: timeout: command not found\n"
|
|
11
|
+
},
|
|
12
|
+
{
|
|
13
|
+
"taskId": "eval-002",
|
|
14
|
+
"taskName": "refactor_code",
|
|
15
|
+
"passed": false,
|
|
16
|
+
"duration": 10,
|
|
17
|
+
"output": "/bin/sh: timeout: command not found\n"
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
"taskId": "eval-003",
|
|
21
|
+
"taskName": "fix_bug",
|
|
22
|
+
"passed": false,
|
|
23
|
+
"duration": 7,
|
|
24
|
+
"output": "/bin/sh: timeout: command not found\n"
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
"taskId": "eval-004",
|
|
28
|
+
"taskName": "add_feature",
|
|
29
|
+
"passed": false,
|
|
30
|
+
"duration": 6,
|
|
31
|
+
"output": "/bin/sh: timeout: command not found\n"
|
|
32
|
+
},
|
|
33
|
+
{
|
|
34
|
+
"taskId": "eval-005",
|
|
35
|
+
"taskName": "code_review",
|
|
36
|
+
"passed": false,
|
|
37
|
+
"duration": 5,
|
|
38
|
+
"output": "/bin/sh: timeout: command not found\n"
|
|
39
|
+
}
|
|
40
|
+
]
|
|
41
|
+
}
|