Forge implementation specifications

Most application developers should start with the Forge developer guides. These documents preserve the implementation decisions, trade-offs, and acceptance criteria behind the platform.

Status: proposed
First consumer: ShareFlow
Implementation language: TypeScript

This directory defines the extraction and migration of a reusable AI platform inspired by the architecture currently used in Twenty. The resulting packages must have no runtime dependency on Twenty or ShareFlow. ShareFlow-specific social tools and workflows remain in an integration package.

Goals

• Provider-neutral model execution using the Vercel AI SDK.
• Durable conversations, runs, typed content parts, checkpoints, cancellation and recovery.
• Threads that carry cross-run session state and compact their own long history.
• User-level memory that follows a principal across their conversations, under their control.
• Permission-filtered tools with lazy discovery and consistent result envelopes.
• Skills, explicit context providers and token-aware context pruning.
• Durable questions and approval gates for external actions.
• Replaceable persistence, vector, blob, queue, lock and realtime adapters.
• Adapters that provision their own schema on startup, like Agno's zero-config setup.
• Tenant-registered outbound MCP servers as first-class, authorization-filtered tools.
• A first-class authorization model filtering tools, retrieval and every store call.
• RAG, attachments, OCR, vision, PDF, document and artifact support.
• GraphQL APIs/subscriptions, headless React hooks and optional UI components.
• Full localization: the backend emits stable codes, the frontend renders them per user locale.
• Token counting, usage/cost accounting with quotas, telemetry and versioned evaluations.

Non-goals

• Recreating Twenty CRM.
• Putting social-media behavior in generic packages.
• Supporting every database or vector store in the first release.
• Allowing a model to write binary files or execute external mutations directly.
• Removing the current Agno runtime before replacement workflows pass parity gates.

Specifications

1. Architecture and package boundaries
2. Core domain and persistence
3. Models, agents, tools, skills and context
4. Durable execution, streaming and HITL
5. RAG, attachments, vision and documents
6. GraphQL and frontend packages
7. ShareFlow integration — moved. The specification is Chorus's product design, not the platform's, and this repository's docs/ tree is published. It lives in the social-integration repository as docs/forge-integration-spec.md.
8. Migration and delivery plan
9. Testing, security and release criteria
10. Outbound MCP integration
11. Authorization
12. Usage, token counting and accounting
13. Sessions, threads and session state
14. Localization (i18n)
15. User-level memory
16. Load, soak and failure injection
17. Security review
18. Data retention
19. Versioning, API surface and deprecation
20. CI, and Jenkins on our own server
21. The platform
22. Glossary
23. Tool catalogue
24. Tool selection at scale
25. The integration page template
26. Retrieval quality, measured
27. The Open Knowledge Format, read against our document model
28. Prompt caching
29. GraphRAG quality, measured
30. Browser isolation

Extraction

• Twenty / Agno extraction inventory
• twenty-sdk vs @agentkit comparison

Governing principles

1. Every tenant-sensitive operation receives an explicit tenant context.
2. Tools are authorization-filtered before discovery and re-authorized during execution.
3. External writes require deterministic validation, idempotency and the configured approval policy.
4. Conversations are owned by the platform, never by a model provider.
5. Infrastructure capabilities are ports with adapter implementations.
6. Large files and tool results are referenced, not injected wholesale into model context.
7. Runtime releases are evaluated against versioned representative cases.