chore: release infrastructure and runtime hardening for v0.1-alpha

.env.example

@@ -4,6 +4,8 @@ OPENAI_API_KEY=sk-...
 
 # --- Server ---
 PORT=3050
+# Comma-separated list of allowed CORS origins (default: localhost:3050,3081)
+# ALLOWED_ORIGINS=http://localhost:3050,http://localhost:3081
 
 # --- Embedding ---
 # EMBEDDING_PROVIDER=openai

.env.test.example

@@ -0,0 +1,8 @@
+# Test environment — copy to .env.test and adjust as needed.
+# Requires a Postgres instance with pgvector extension.
+# Use `docker compose up postgres -d` to start one locally.
+
+DATABASE_URL=postgresql://supermem:supermem@localhost:5433/supermem
+OPENAI_API_KEY=test-placeholder
+EMBEDDING_DIMENSIONS=1024
+PORT=3051

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @ethanj

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,49 @@
+name: Bug Report
+description: Report a bug in Atomicmemory-core
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear description of the bug.
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Minimal steps to reproduce the behavior.
+      placeholder: |
+        1. Start the server with `docker compose up`
+        2. POST to /memories/ingest with ...
+        3. See error ...
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What you expected to happen.
+
+  - type: dropdown
+    id: embedding-provider
+    attributes:
+      label: Embedding provider
+      options:
+        - openai
+        - openai-compatible
+        - ollama
+        - transformers
+
+  - type: input
+    id: node-version
+    attributes:
+      label: Node.js version
+      placeholder: "22.x"
+
+  - type: input
+    id: postgres-version
+    attributes:
+      label: PostgreSQL version
+      placeholder: "17 with pgvector"

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,33 @@
+name: Feature Request
+description: Suggest a new feature for Atomicmemory-core
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this feature solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How should this work?
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What other approaches did you consider?
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope
+      description: Does this belong in the core runtime or the research repo?
+      options:
+        - Core runtime (API, ingest, search, storage)
+        - Research (benchmarks, eval, design exploration)
+        - Not sure

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## What changed
+
+<!-- Brief description of the change and why -->
+
+## Checklist
+
+- [ ] `npx tsc --noEmit` — type check passes
+- [ ] `npm test` — all tests pass
+- [ ] `fallow` — reports no issues
+- [ ] Changes are to runtime behavior (not research/eval)
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactoring (no behavior change)
+- [ ] Documentation
+- [ ] CI / infrastructure

.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: pgvector/pgvector:pg17
+        env:
+          POSTGRES_USER: atomicmem
+          POSTGRES_PASSWORD: atomicmem
+          POSTGRES_DB: atomicmem_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U atomicmem"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    env:
+      DATABASE_URL: postgresql://atomicmem:atomicmem@localhost:5432/atomicmem_test
+      OPENAI_API_KEY: test-placeholder
+      EMBEDDING_DIMENSIONS: 1024
+      PORT: 3051
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Code health (fallow)
+        run: npx fallow --no-cache
+
+      - name: Run tests
+        run: npm test

.github/workflows/release.yml

@@ -0,0 +1,59 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: pgvector/pgvector:pg17
+        env:
+          POSTGRES_USER: atomicmem
+          POSTGRES_PASSWORD: atomicmem
+          POSTGRES_DB: atomicmem_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U atomicmem"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    env:
+      DATABASE_URL: postgresql://atomicmem:atomicmem@localhost:5432/atomicmem_test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Code health (fallow)
+        run: npx fallow --no-cache
+
+      - name: Run tests
+        run: npm test
+
+      - name: Verify Docker build
+        run: docker build -t atomicmemory-core:${{ github.ref_name }} .
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-04-15
+
+### Added
+- Initial extraction from atomicmemory-research prototype
+- Express API server with memory ingest, search, and consolidation endpoints
+- Postgres + pgvector storage backend
+- Pluggable embedding providers: openai, openai-compatible, ollama, transformers (WASM)
+- AUDN mutation engine (Add, Update, Delete, No-op) with fail-closed semantics
+- Contradiction-safe claim versioning
+- Hybrid retrieval (vector + BM25/FTS)
+- Tiered context packaging
+- Entity graph with spreading activation
+- Docker and Railway deployment support
+- 869 tests across 79 test files
+- CI with GitHub Actions (typecheck, fallow, tests)
+- Contributor docs (CONTRIBUTING.md, issue/PR templates)

CLAUDE.md

@@ -0,0 +1,87 @@
+# Atomicmemory-core
+
+Open-source memory engine for AI applications. Docker-deployable backend with
+semantic retrieval, AUDN mutation, and contradiction-safe claim versioning.
+
+## Architecture
+
+- **Runtime**: Express server (TypeScript, ESM)
+- **Storage**: Postgres + pgvector
+- **Embeddings**: Pluggable (openai, openai-compatible, ollama, transformers/WASM)
+- **Structure**: Single-package repo. Routes → Services → Repository → Postgres.
+
+### Key modules
+- `src/routes/` — Express route handlers
+- `src/services/` — Business logic (ingest, search, AUDN, packaging)
+- `src/db/` — Repository layer, schema, migrations
+- `src/services/memory-service.ts` — Thin facade delegating to focused sub-modules
+- `src/services/memory-ingest.ts` — Ingest pipeline
+- `src/services/memory-search.ts` — Search/retrieval pipeline
+- `src/services/memory-audn.ts` — AUDN mutation decisions
+- `src/services/memory-crud.ts` — List/get/delete/consolidate
+- `src/services/memory-storage.ts` — Canonical fact storage and projections
+
+### Boundary rule
+This repo is the **releaseable runtime engine**. Eval harnesses, benchmarks,
+competitive analysis, and design explorations belong in `atomicmemory-research`.
+If it changes shipped backend behavior, it belongs here. If it only changes
+benchmark outputs or scoring methodology, it belongs in research.
+
+## Development Guidelines
+
+### Code Style & Standards
+- Files must be smaller than 400 lines excluding comments. Refactor when exceeded.
+- Functions must be smaller than 40 lines excluding comments and catch/finally blocks.
+- Test files must be smaller than 400 lines. Tests must be smaller than 40 lines.
+- Use TypeScript with proper types for all variables, parameters, and return values.
+- Use interfaces for object shapes. Avoid `any`. Use generics when appropriate.
+- Use optional chaining (`?.`) and nullish coalescing (`??`).
+- No fallback modes — if something fails, fail closed, don't run degraded.
+- No silent error catching — all errors must be logged or propagated.
+- No direct access to env vars (use `src/config.ts`).
+- No hardcoded values — use named constants.
+- No timing-based solutions in code or tests. All solutions must be deterministic.
+
+### Clean Code Rules
+- Meaningful names that reveal purpose.
+- One function, one responsibility.
+- Avoid magic numbers — use named constants.
+- Keep code DRY. Duplicate code means duplicate bugs.
+- Avoid deep nesting — flatten control flow.
+- Comment why, not what.
+- Limit function arguments — group related data into objects.
+
+### Comments and Documentation
+- Include a JSDoc comment at the top of each file.
+- Write clear comments for complex logic.
+- Document public APIs and functions.
+- Keep comments up-to-date with code changes.
+
+### Pre-Commit Checks
+
+Before committing any work:
+
+1. `npx tsc --noEmit` — type-check passes
+2. `npm test` — all tests pass (requires Postgres via .env.test)
+3. `fallow --no-cache` — zero issues (dead code, duplication, complexity). Always use `--no-cache` before committing to match CI behavior. Use `fallow fix --dry-run` to preview, `fallow fix --yes` to apply. Fix remaining issues manually.
+
+### Running Tests
+- Full suite: `npm test` (requires DATABASE_URL in .env.test pointing to Postgres with pgvector)
+- Single test: `dotenv -e .env.test -- npx vitest run "src/**/__tests__/<path>" --reporter verbose`
+- Deployment tests: `npm run test:deployment`
+- Docker smoke: `npm run test:docker-smoke`
+
+### Git Workflow
+- Never commit directly to main. Always create a branch.
+- Do not commit until changes are approved by the user.
+- When committing, create a temporary `commit-message.txt` and use `-F`, then delete.
+- When creating a PR, create a temporary `pr-description.md`, use `gh pr create --body-file`, then delete.
+- Never use `git reset --hard`.
+
+## General Rules
+
+1. Read the codebase before making changes. Never speculate about code you haven't opened.
+2. Check in with the user before making major changes.
+3. Make every change as simple as possible — minimal impact, maximum clarity.
+4. Check for existing implementations before writing new code.
+5. Mutations must fail closed — no silent fallback-to-ADD on UPDATE/DELETE/SUPERSEDE errors.

CODE_OF_CONDUCT.md

@@ -0,0 +1,38 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers. All complaints will be reviewed and
+investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.