Durable, project-scoped memory and semantic retrieval for AI agents and developer tools.
FORGE is a provider-agnostic persistence layer for durable project knowledge. It gives agents and humans one relational source of truth for memories, decisions, documents, executions and auditable context, with optional vector retrieval through pgvector.
FORGE is not an agent framework and does not call an embedding model from its core. Model providers remain replaceable external workers.
The official geometric identity and usage rules live in the brand pack.
Project status: alpha. The schema and local Workbench are validated on PostgreSQL 18.4 with pgvector 0.8.2; PostgreSQL 14+ is the compatibility target. APIs may evolve before 1.0.
- Project isolation: relational and semantic reads cannot cross projects.
- Database-enforced invariants: optimistic locking, append-only history and managed identity rules survive application bugs.
- Provider independence: embeddings and reranking stay outside Core.
- Agent and human access: MCP tools and a loopback-only local Workbench use the same Gateway contracts.
- Reproducible evolution: transactional, checksum-aware migrations and idempotent write contracts.
- Verified recovery: authenticated encrypted backups restore only into an empty database and prove migration checksums and table counts afterwards.
| Package | Current version | Responsibility |
|---|---|---|
schema |
0.1.3 | PostgreSQL migrations and invariant tests |
persistence-gateway |
0.1.5 | Typed transactions and domain workflows |
mcp-server |
0.1.5 | Strict stdio MCP adapter |
embedding-worker |
0.1.6 | Provider-pluggable indexing worker |
semantic-bridge |
0.1.4 | Natural-language search and optional reranking |
resilience |
0.2.0 | Encrypted backup, verification and safe restore |
workbench |
0.1.1 | Local human-facing web application |
flowchart LR
Agents["Agents / MCP clients"] --> MCP["MCP Server"]
Humans["Browser on loopback"] --> WB["Workbench"]
MCP --> GW["Persistence Gateway"]
WB --> GW
WB --> SB["Semantic Bridge"]
SB --> GW
Worker["Embedding Worker"] --> GW
Worker --> Provider["External model provider"]
SB --> Provider
GW --> DB["PostgreSQL + optional pgvector"]
Recovery["Resilience CLI"] --> DB
Recovery --> Backup["Authenticated encrypted recovery package"]
See Architecture and the decision records for boundaries and trade-offs.
Prerequisites: Node.js 20+ and npm 10+.
git clone https://github.com/BlinkStreamTeam/Forge.git
cd Forge
npm install
npm run build
npm testThe default test suite uses an embedded PostgreSQL-compatible runtime where possible and does not require credentials. Native PostgreSQL, pgvector and LM Studio validation are opt-in; see each package README:
- Schema and migrations
- Persistence Gateway
- MCP Server
- Embedding Worker
- Semantic Bridge
- Resilience
- Workbench
FORGE treats PostgreSQL as the source of persistent truth. The Workbench binds only to loopback, keeps database credentials out of browser state and places all writes behind Gateway validation and idempotency contracts. Never expose the local Workbench directly to a network.
Please report vulnerabilities using the process in SECURITY.md.
Read CONTRIBUTING.md before proposing changes. New behavior must preserve the invariants documented in Architecture and include tests at the narrowest useful boundary.
Licensed under the Apache License 2.0.