Contributing to CORTEX

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• README.md
• package.json
• src/mcp/server.ts
• src/ingestion/ingest-markdown.ts
• benchmarks/cogbench/README.md
• paper/reproducer/README.md
• src/index.ts

CORTEX is a synthetic cognition infrastructure for AI agents, modeled on mammalian hippocampal-cortical circuits. The project welcomes contributions that enhance its memory architecture, including improvements to learning, consolidation, and retrieval mechanisms grounded in neuroscience.

Contributors help maintain a production-grade system that powers agents with persistent, evolving memory. The scope of contributions ranges from core architectural changes in the Hippocampus to expanding the MCP Toolset or improving Benchmarking accuracy.

Sources: README.md:1-12, CONTRIBUTING.md:1-2

Development Workflow

Contributors must follow a structured workflow to ensure code quality and system stability. All code changes undergo rigorous testing and type checking before being merged into the main repository.

Getting Started Steps

1. Fork the CORTEX repository.
2. Create a specific feature branch using git checkout -b feature/my-feature.
3. Implement your changes following the Code Guidelines.
4. Run the test suite via npm test.
5. Execute type checking via npm run typecheck.
6. Commit changes with clear, descriptive messages.
7. Open a pull request for review.

Sources: CONTRIBUTING.md:5-12

Environment Setup

The development environment requires Node.js 22+ and PostgreSQL 15+ with the pgvector extension.

git clone https://github.com/YOUR_USERNAME/cortex.git
cd cortex
npm install
cp .env.example .env
# Configure DATABASE_URL and embedding API keys in .env
npx tsx scripts/run-migrations.ts
npm test

Sources: CONTRIBUTING.md:14-22, README.md:129-140

Contribution Lifecycle

The following diagram illustrates the path from local development to a merged pull request:

The diagram shows the sequence of technical checks required for every contribution.
Sources: CONTRIBUTING.md:5-22, package.json:11-26

Code Guidelines

CORTEX maintains strict engineering standards to ensure the reliability of its cognitive architecture.

• TypeScript Strict Mode: The project enforces strict typing to prevent runtime errors.
• Security: You must not hardcode API keys, file paths, or personal data.
• Database Migrations: You must implement database changes through initDatabase() migrations using IF NOT EXISTS guards.
• Feature Testing: New features must include corresponding tests to maintain coverage.
• MCP Standards: Tools must provide clear descriptions and strictly typed parameters using Zod schemas.

Sources: CONTRIBUTING.md:24-30

Core Subsystems for Contribution

Contributors can focus on several distinct layers of the cognitive architecture.

Ingestion Pipeline

The ingestion system handles the transformation of raw data into episodic memory. It involves chunking, embedding, entity extraction, and emotional valence analysis.

The diagram outlines the data flow during the ingestion of new information.
Sources: src/ingestion/ingest-markdown.ts:74-135, README.md:58-69

MCP Server Development

The src/mcp/server.ts file defines the tools available to MCP-compatible agents like Claude Code. When adding a tool, you must define its parameters using Zod.

Tool Component	Responsibility
Tool Name	Unique identifier (e.g., cortex_search).
Description	Explains when the agent should use the tool.
Zod Schema	Defines input validation and types.
Handler	The async logic performing the memory operation.

Sources: src/mcp/server.ts:40-60, CONTRIBUTING.md:29-30

Hippocampal Subsystem

This layer handles pattern separation (Dentate Gyrus), novelty detection (CA1), and autoassociative recall (CA3). Contributions here typically involve adjusting sparse coding parameters or refining novelty detection logic.

Sources: README.md:73-78, paper/drafts/cortex-v2-4-technical-note.md:43-69

Benchmarking and Validation

CORTEX prioritizes measurable performance. Contributors adding features should validate them against the project's benchmark suites.

Key Benchmark Frameworks

• LongMemEval: Measures retrieval accuracy across 500 questions.
• LoCoMo: Evaluates long-term conversational memory across 1,540 questions.
• CogBench: Tests 7 cognitive capabilities including temporal validity, reconsolidation, and procedural learning.

Sources: BENCHMARKS.md:1-25, benchmarks/cogbench/README.md:15-30

Running Benchmarks

To reproduce baseline results before submitting changes:

1. Ensure the database is running via Docker or a local instance.
2. Run bash paper/reproducer/run_full.sh for the full suite.
3. Use npx tsx benchmarks/cogbench/run.ts for cognitive capability testing.

Sources: paper/reproducer/README.md:10-20, benchmarks/cogbench/README.md:50-65

Priority Areas for Help

The maintainers have identified specific modules that require community assistance:

• Entity Resolution: Improving Named Entity Recognition (NER), co-reference resolution, and entity deduplication.
• Temporal Reasoning: Developing APIs for timeline queries and tracking changes over time.
• Graph Visualization: Building explorers for the memory network using D3 or Three.js.
• Providers: Adding support for additional embedding models and local LLM integrations.
• Tests: Expanding test coverage beyond the current hippocampus, entities, and chunker modules.

Sources: CONTRIBUTING.md:32-38

Conclusion

Contributing to CORTEX involves adhering to strict TypeScript standards, implementing neuroscience-grounded logic, and validating changes through comprehensive benchmarks. By following the established development workflow and focus areas, contributors ensure that AI agents maintain stable, meaningful, and evolving long-term memory.

Sources: README.md:25-30, CONTRIBUTING.md:5-12