Afelu Memory

Afelu Memory is a multilingual operations assistant for small businesses. It turns conversations into durable business memory, retrieves the right context in later sessions, and converts time-sensitive commitments into clear next actions.

Built for the CockroachDB × AWS Hackathon: Build with Agentic Memory.

Why it exists

Small-business knowledge often lives in chat threads and in the owner's head: a customer's delivery promise, a supplier price change, or a minimum-margin rule. Ordinary chat assistants lose that context between sessions. Afelu Memory preserves only durable, useful facts and shows how recalled memories influence each response.

How it works

1. A business owner describes a customer promise, supplier change, or operating rule.
2. Amazon Titan Text Embeddings V2 converts the message into a 1,024-dimension vector.
3. CockroachDB stores the memory event, structured metadata, embedding, tasks, and audit records in one system of record.
4. A later request performs tenant-scoped semantic retrieval through a CockroachDB prefix-column vector index.
5. Amazon Nova Lite receives the retrieved context through the Bedrock Converse API and returns a response plus an optional durable memory or follow-up task.
6. The application records which memories influenced the run, making the agent's behavior inspectable.

Architecture

Browser
  |
  v
Next.js application on AWS
  |-- Amazon Bedrock Converse --> Amazon Nova Lite
  |-- Amazon Bedrock InvokeModel --> Titan Text Embeddings V2
  `-- PostgreSQL wire protocol --> CockroachDB Cloud
         |-- structured memory and tasks
         |-- VECTOR(1024) embeddings
         `-- tenant-prefixed distributed vector index

The runtime never sends database or AWS credentials to the browser. tenant_id is the prefix column of the semantic index and is constrained in every retrieval query.

Technology

• Next.js 15, React 19, and TypeScript
• Amazon Bedrock with the EU Nova Lite inference profile
• Amazon Titan Text Embeddings V2
• CockroachDB Cloud for persistent state and distributed vector search
• CockroachDB Cloud Managed MCP Server for schema inspection and operational verification
• AWS hosting for the functional application

Run locally

Requirements

• Node.js 20–24
• A CockroachDB Cloud cluster
• AWS credentials with permission to invoke the configured Bedrock models in eu-west-1

Install

npm install
cp .env.example .env.local

Set DATABASE_URL to a TLS-enabled CockroachDB connection string. Keep the verified defaults for:

AWS_REGION=eu-west-1
BEDROCK_CHAT_MODEL_ID=eu.amazon.nova-lite-v1:0
BEDROCK_EMBEDDING_MODEL_ID=amazon.titan-embed-text-v2:0
AFELU_DEMO_MODE=false

On AWS, set DATABASE_SECRET_ID instead of DATABASE_URL. The SSR compute role reads the connection URL from AWS Secrets Manager at runtime, so the credential is not written into Amplify build artifacts.

Use ccloud to open the cluster SQL shell:

ccloud cluster sql <cluster-name>

Apply db/schema.sql in that shell or with the CockroachDB SQL client and a privileged migration identity:

cockroach sql --url "$DATABASE_URL" --file db/schema.sql

Then start the application:

npm run dev

Open http://localhost:3000.

Database design

db/schema.sql creates:

• memory_events: durable facts, source text, importance, timestamps, and 1,024-dimension embeddings
• tasks: open, completed, or cancelled follow-up work
• agent_runs: retrieved memory IDs and outcome flags for each run
• audit_log: tenant-scoped operational audit records
• tenants: workspace identity and locale

The semantic index is defined as:

VECTOR INDEX memory_events_semantic_idx
  (tenant_id, embedding vector_cosine_ops)

CockroachDB must have vector indexing enabled before applying the schema. Use a privileged migration identity for schema changes and a separate least-privilege identity for the application runtime.

Demo mode

AFELU_DEMO_MODE=true is an explicit local-only presentation mode with synthetic data and deterministic responses. It is never enabled implicitly. The judged deployment must use AFELU_DEMO_MODE=false with live CockroachDB and Bedrock integrations.

Verification

npm run typecheck
npm run lint
npm run build
npm audit --omit=dev

For an end-to-end check, enter a durable fact, start a later conversation, and verify that:

1. a row and vector were written to memory_events;
2. the later response reports at least one retrieved memory;
3. the corresponding agent_runs row contains the retrieved memory ID;
4. any requested follow-up appears in tasks.

The Managed MCP connection can be kept read-only for this inspection.

Security

• Use IAM Identity Center for administrators and an IAM role for the deployed workload.
• Grant only bedrock:InvokeModel for the models used by the application.
• Store DATABASE_URL in a server-side secret store; never expose it through NEXT_PUBLIC_* variables.
• On Amplify Hosting, attach a least-privilege SSR compute role and store the database URL in AWS Secrets Manager.
• Use TLS for every CockroachDB connection.
• Use synthetic business data in the public demo.
• Add authenticated tenant membership and authorization checks before admitting external workspaces.

License

MIT