February 8, 2026 5 min read TypeScript fork

core

Abstract

Build your digital brain which can talk to your AI apps.

The Problem

Developers building AI‑augmented applications need a persistent “brain” that can store conversational context, retrieve relevant episodes, and trigger actions across many tools. Without a unified store, each app maintains its own silo, forcing developers to duplicate memory logic and lose coherence when users switch between services.

What This Does

core implements a memory agent that persists “episodes” in Neo4j, indexes them in a vector store, and exposes a React‑based UI for exploration and management. The main server lives under apps/webapp/ and is bootstrapped by the Vite config apps/webapp/vite.config.ts. UI components such as apps/webapp/app/components/conversation/*.tsx render chat streams, while apps/webapp/app/components/graph/*.tsx visualise topic graphs. Integration adapters (e.g., integrations/github/, integrations/discord/) provide plug‑ins that push and pull episode data via the core services.

Key files:

apps/webapp/app/bullmq/queues/index.ts – registers background queues.
apps/webapp/app/bullmq/workers/index.ts – starts workers that ingest new messages.
apps/webapp/app/services/logger.service.ts – centralised logging used by most modules.
packages/providers/src/graph/neo4j/index.ts – thin wrapper around Neo4j driver used by the ingestion pipeline.

How It Is Wired

Execution starts when Vite launches the server defined in apps/webapp/app/entry.server.tsx. The server imports apps/webapp/app/bullmq/start-workers.ts, which in turn loads the queue definitions from apps/webapp/app/bullmq/queues/index.ts. Each queue enqueues a job that eventually reaches a worker defined in apps/webapp/app/bullmq/workers/index.ts.

A typical ingestion flow:

API endpoint (apps/webapp/app/components/api/index.ts) receives a POST with a new message.
It calls apps/webapp/app/trigger/ingest/ingest.ts (part of an import cycle; see health section).
ingest.ts creates a BullMQ job via apps/webapp/app/bullmq/connection.ts.
The worker (apps/webapp/app/bullmq/workers/index.ts) processes the job, invoking apps/webapp/app/lib/utils.ts for payload normalization and then packages/providers/src/graph/neo4j/core.ts to persist the episode.
After storage, the worker pushes the episode’s embedding to the vector store (code located in packages/providers/src/vector-store/).

Blast‑radius hubs – modules with the highest inbound imports:

Hub module	Ca (importers)	Ce (imports)	Instability
`apps/webapp/app/components/ui/index.ts`	25	6	0.19
`apps/webapp/app/lib/utils.ts`	25	0	0
`apps/webapp/app/components/icons/types.tsx`	22	0	0

These files are touched by many downstream components; any change here will affect dozens of UI paths.

Circular imports – 11 modules participate in cycles; e.g., packages/emails/src/transports/index.ts ↔ apps/webapp/app/trigger/utils/queue.ts. Such cycles increase cognitive load and risk of runtime errors when refactoring.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/core
cd core

# Install dependencies (pnpm is the declared package manager)
pnpm install

# Copy example env and fill secrets
cp .env.example .env
# Edit .env (or hosting/docker/.env) with:
#   NEO4J_PASSWORD, POSTHOG_PROJECT_KEY, MAGIC_LINK_SECRET, etc.

# Run locally (Vite dev server)
pnpm dev   # starts the webapp on http://localhost:5173

# Or build and run the Docker image
docker build -t core .
docker run -p 3000:3000 --env-file .env core

The UI is reachable at the server’s root. API calls are routed through apps/webapp/app/components/api/ and background processing is handled by the BullMQ workers started automatically on server start.

Real‑World Use

A SaaS product that offers AI‑assisted customer support can embed the Core SDK (found under packages/providers/) in its backend. When a support ticket arrives, the service posts the ticket text to Core’s /api/v1/ingest endpoint. Core stores the episode in Neo4j, creates an embedding, and makes it searchable for future tickets. The product’s UI then uses apps/webapp/app/components/graph/graph-client.tsx to display related past tickets, enabling agents to surface prior resolutions instantly.

Code Health & Issues

Measured findings (static analysis)

HIGH/clarity – Hub modules (e.g., apps/webapp/app/components/ui/index.ts) have 25+ dependents; keep them stable.
HIGH/soundness – 11 import cycles (e.g., packages/emails/src/transports/index.ts). Break cycles by extracting shared types.
HIGH/cognitive_load – Deep nesting (max depth 6) in several components; refactor with early returns.
HIGH/cognitive_load – Oversized files (> 1 k lines) such as apps/webapp/app/components/onboarding/provider-config.tsx. Split by responsibility.
HIGH/clarity – Repeated 6‑line blocks across > 200 files; extract helpers.
MEDIUM/resilience – Empty catch {} blocks in two files; add logging or rethrow.
MEDIUM/cognitive_load – High branching density in three utility files; consider strategy tables.

Code‑health audit (severity‑ranked)

CRITICAL – Committed credentials in hosting/docker/.env (MAGIC_LINK_SECRET, NEO4J_PASSWORD, POSTHOG_PROJECT_KEY). Rotate and remove from repo.
HIGH – .env is tracked despite .gitignore; git rm --cached hosting/docker/.env and rotate keys.
HIGH – GitHub Actions use tag references; pin each action to a SHA.
HIGH – No test suite; add tests for each public entry point and run them in CI.
HIGH – Wildcard CORS ("*" in apps/webapp/server.ts); replace with explicit origins.
MEDIUM – GITHUB_TOKEN permissions not declared; add least‑privilege scopes.
MEDIUM – Dependabot not configured; add .github/dependabot.yml.
MEDIUM – No dependency‑vulnerability gate; add dependency-review-action or osv-scanner.
MEDIUM – No pre‑commit secret scan; install a hook (e.g., detect-secrets).

The Bottom Line

core provides a full‑stack memory‑agent with a React UI, Neo4j backing, and extensible integration points, making it a solid foundation for AI‑driven apps. However, the repository currently ships live credentials, lacks automated tests, and contains several high‑impact architectural smells (hub modules, import cycles). Addressing the health issues and adding a test suite should be priority steps before adopting it in production.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

988 files

TypeScript355
TSX255
SQL69
JSON59
Markdown26
YAML23

ReactTailwindDockerVector storeNeo4j

Module dependencies

The 10 most depended-upon modules of 626, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_bapp_app_components_ui_index["index"] n1_apps_webapp_app_lib_utils["utils"] n2_p_app_components_icons_types["types"] n3__app_services_logger_service["logger.service"] n4_viders_src_graph_neo4j_types["types"] n5_oviders_src_graph_neo4j_core["core"] n6_app_app_trigger_utils_prisma["prisma"] n7_p_app_trigger_utils_provider["provider"] n8_pp_app_components_icon_utils["icon-utils"] n9_pp_app_components_graph_type["type"] n5_oviders_src_graph_neo4j_core --> n4_viders_src_graph_neo4j_types

Dependencies

45 of 120 declared dependencies are a major version behind. Resolved 116 of 120 against the registry.

Package	Declared	Latest	Behind
`cross-env`	^7.0.3	10.1.0	3 major
`nanoid`	3.3.8	6.0.1	3 major
`ollama-ai-provider-v2`	1.5.1	4.0.1	3 major
`react-resizable-panels`	^1.0.9	4.12.2	3 major
`@ai-sdk/amazon-bedrock`	3.0.47	5.0.66	2 major
`openai`	^5.12.2	7.4.0	2 major
`@ai-sdk/anthropic`	^3.0.9	4.0.39	1 major
`@ai-sdk/google`	^3.0.6	4.0.44	1 major

Findings

LowSecret-shaped paths present; the code-health audit confirms or clears them hosting/docker/.env, packages/database/.env

Open in Code Brain → See its neighbourhood →

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

critical2

high6

medium6

low1

Upgrade the pinned dependency carrying a critical advisorycritical

@remix-run/node@2.1.0 CVE-2025-61686 (critical)

The manifest pins the exact version the advisory covers, so this is not a warning about drift: the vulnerable code is what installs, and a critical rating means it is reachable over the network without credentials or user interaction.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Rotate the credentials in the committed environment filecritical3 occurrences

hosting/docker/.env

MAGIC_LINK_SECRET, NEO4J_PASSWORD, POSTHOG_PROJECT_KEY hold generated values

These values are loaded by the application at boot, so a generated value here is a working credential for something that runs.

Fix: Rotate each named credential, remove the file from the index, and replace it with a keys-only example.

Untrack the file your own .gitignore says to ignorehigh

hosting/docker/.env

tracked although .gitignore excludes it

The author already decided this file must never be committed, so its presence is an accident nobody noticed, which means the credentials in it are the ones actually in use.

Fix: git rm --cached the path and rotate; the ignore rule is already correct.

Pin third-party GitHub Actions to a commit SHAhigh5 occurrences

.github/workflows

docker/setup-qemu-action@v3, docker/setup-buildx-action@v3, docker/build-push-action@v5, pnpm/action-setup@v2.2.4

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Upgrade the pinned dependency carrying a published advisoryhigh7 occurrences

@modelcontextprotocol/sdk@1.25.3 CVE-2026-25536 (high); @remix-run/react@2.16.7 CVE-2025-59057 (high) +1 more; @remix-run/server-runtime@2.16.7 CVE-2026-42342 (high) +1 more; nanoid@3.3.8 CVE-2026-67214 (high) +1 more

The pinned version is the one that installs, so a published advisory against it describes this deployment rather than a hypothetical one, and the advisory is also a public description of how to exploit it.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Add a test suite; this repository has nonehigh629 occurrences

629 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Remove the committed .env and rotate what it holdshigh2 occurrences

hosting/docker/.env

hosting/docker/.env, packages/database/.env

A tracked .env is the most common route for a working key to reach a public clone, and it is the file the app actually loads, so the value is usually live.

Fix: git rm --cached the file, add it to .gitignore, rotate every credential it names, commit a .env.example with empty values.

Replace the wildcard CORS origin with an explicit allow listhigh

apps/webapp/server.ts

Access-Control-Allow-Origin", "*"

Any page on the internet can call the API with the browser's cookies attached, so a logged-in visitor to an unrelated site performs authenticated requests without knowing, and the wildcard combined with credentials is the exact configuration browsers refuse for that reason.

Fix: List the origins the API actually serves, and never pair a wildcard with credentials.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/build-docker-image.yml

2 workflow(s) declare no permissions, 2 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

26 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Add a pre-commit secret gatemedium

a secret-shaped file is tracked and no repo-level gate is visible

Without a gate the same class of leak recurs on the next commit, so a leak finding is the symptom and this is the cause.

Fix: Add a pre-commit hook scanning staged content, and enable push protection.

3 further finding(s) are listed in the full report.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.

View on GitHub All Projects