{"id":40476113,"url":"https://github.com/nbursa/inception-core-server","last_synced_at":"2026-01-20T18:24:31.433Z","repository":{"id":297526843,"uuid":"994389669","full_name":"nbursa/inception-core-server","owner":"nbursa","description":"A modular, extensible Rust-based server providing short-term, long-term, and latent memory services, a chat endpoint with a BaseAgent + Sentience DSL, and integration with ChromaDB and LLM services.","archived":false,"fork":false,"pushed_at":"2025-07-15T15:12:25.000Z","size":299,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-19T21:24:27.619Z","etag":null,"topics":["agent-framework","ai-agents","autonomous-agents","axum","chromadb","docker","dsl","experimental","inference","llm","memory","rust","sqlite","vector-search"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nbursa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-01T20:42:30.000Z","updated_at":"2025-07-15T15:12:28.000Z","dependencies_parsed_at":"2025-06-06T00:26:33.255Z","dependency_job_id":"6a11975a-cc16-4951-9122-42e2b66fb5fd","html_url":"https://github.com/nbursa/inception-core-server","commit_stats":null,"previous_names":["nbursa/inception-mcp-server"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/nbursa/inception-core-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbursa%2Finception-core-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbursa%2Finception-core-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbursa%2Finception-core-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbursa%2Finception-core-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nbursa","download_url":"https://codeload.github.com/nbursa/inception-core-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nbursa%2Finception-core-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28609040,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","ai-agents","autonomous-agents","axum","chromadb","docker","dsl","experimental","inference","llm","memory","rust","sqlite","vector-search"],"created_at":"2026-01-20T18:24:31.319Z","updated_at":"2026-01-20T18:24:31.417Z","avatar_url":"https://github.com/nbursa.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Inception ICORE Server\n\n![Status: WIP](https://img.shields.io/badge/status-WIP-orange)\n![License: Non-Commercial](https://img.shields.io/badge/license-Proprietary%20NC-blue)\n![Language: Rust](https://img.shields.io/badge/language-Rust-orange)\n![Dockerized](https://img.shields.io/badge/docker-ready-blue)\n![Build](https://img.shields.io/badge/build-manual-lightgrey)\n\n\u003e **Inception core (ICORE) Server**  \n\u003e A modular, extensible Rust-based server providing short-term, long-term, and latent memory services, a chat endpoint with a BaseAgent + Sentience DSL, and integration with ChromaDB and LLM services.\n\n\u003e ⚠️ **Work In Progress**: This project is under active development. Interfaces, APIs, and internal structure may change frequently.\n\n---\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Features](#features)\n3. [Architecture \u0026 Components](#architecture--components)\n   1. [BaseAgent \u0026 Sentience DSL](#baseagent--sentience-dsl)\n   2. [Memory Layers](#memory-layers)\n      - [Short-Term Memory](#short-term-memory)\n      - [Long-Term Memory](#long-term-memory)\n      - [Latent Memory (ChromaDB)](#latent-memory-chromadb)\n   3. [LLM Integration](#llm-integration)\n   4. [HTTP API (Axum)](#http-api-axum)\n4. [Getting Started](#getting-started)\n   1. [Prerequisites](#prerequisites)\n   2. [Clone \u0026 Build](#clone--build)\n   3. [Environment Variables](#environment-variables)\n   4. [Running with Docker Compose](#running-with-docker-compose)\n   5. [Running Locally without Docker](#running-locally-without-docker)\n   6. [Testing the Server](#testing-the-server)\n5. [Configuration \u0026 Environment Variables](#configuration--environment-variables)\n6. [API Reference](#api-reference)\n   1. [Health Check](#health-check)\n   2. [Short-Term Memory Endpoints](#short-term-memory-endpoints)\n   3. [Long-Term Memory Endpoints](#long-term-memory-endpoints)\n   4. [Latent Memory (ChromaDB) Endpoints](#latent-memory-chromadb-endpoints)\n   5. [Chat Endpoint](#chat-endpoint)\n   6. [Sentience DSL Endpoint](#sentience-dsl-endpoint)\n7. [Agent DSL (“Sentience”) Details](#agent-dsl-sentience-details)\n8. [Directory Structure](#directory-structure)\n9. [Logging \u0026 Monitoring](#logging--monitoring)\n10. [Development Workflow](#development-workflow)\n11. [Contributing](#contributing)\n12. [License](#license)\n\n---\n\n## Overview\n\n**Inception ICORE Server** is designed as a highly flexible microservice that facilitates:\n\n- **Short-Term Memory** for transient key-value storage (in-memory).\n- **Long-Term Memory** for persistent key-value storage (SQLite).\n- **Latent Memory** (vector embeddings + similarity search) backed by ChromaDB.\n- A **BaseAgent** capable of “remember/recall/if context” operations, with an optional **Sentience DSL** layer that can be loaded at runtime.\n- A **Chat** endpoint that routes incoming messages first to the Sentience DSL (if loaded), then falls back to a standard BaseAgent, and finally to a fallback LLM.\n- A simple, well-documented **HTTP API** (built on [Axum](https://github.com/tokio-rs/axum)) for interacting with all layers of memory and agent functionality.\n\nThis README will guide you through architecture details, setup instructions, environment configuration, API usage, and development workflows.\n\n\u003e See [VISION.md](./VISION.md) for the philosophical motivation and long-term intent behind this project.\n\n---\n\n## Features\n\n- **Modular Memory Layers**\n\n  - **Short-Term**: Fast, in-memory key-value store (volatile).\n  - **Long-Term**: Persistent SQLite-backed key-value store.\n  - **Latent Memory**: Vector embeddings and nearest-neighbor queries via ChromaDB.\n\n- **Agent Logic**\n\n  - **BaseAgent**: Simple “remember”, “recall”, and “if context includes” logic.\n  - **Sentience DSL**: Loadable DSL for scripting custom response logic, with seamless seeding/flushing of memory layers.\n\n- **LLM Fallback**\n\n  - Out-of-the-box integration with any HTTP-based LLM (e.g., a local Llama server) for fallback generation.\n\n- **HTTP API**\n\n  - Exposes endpoints for managing memory, embedding/querying vectors, chatting, and running DSL code directly.\n  - JSON-based request/response formats.\n\n- **Docker Compose Setup**\n\n  - Preconfigured `docker-compose.dev.yml` to orchestrate ChromaDB, a local LLM service, and the ICORE Server.\n\n- **Asynchronous**\n\n  - Built on Rust’s Tokio runtime for high concurrency and performance.\n\n- **Extensible \u0026 Configurable**\n  - Easily swap out ChromaDB URL, LLM URL, database paths, and DSL scripts via environment variables.\n\n---\n\n## Architecture \u0026 Components\n\n### Architecture as Brain\n\nThe inception-ICORE-server acts as the brain stem of an artificial intelligence system — responsible for coordination, memory routing, and protocol-level reflexes.\n\nIts structure is inspired by the biological brain:\n\n- **Inception (this server)** — _Brain stem_\n  Manages memory access, agent execution, and DSL processing. It doesn't \"think\" — it regulates.\n\n- **Cortex (Memory layers)** — _Cognitive cortex_  \n  Stores long-term knowledge (SQLite), short-term working memory (in-memory), and latent semantic space (ChromaDB).\n\n- **Agents** — _Organs_  \n  Input/output entities that perceive, act, and reflect using structured memory and embedded logic.\n\n- **ICORE Protocol** — _Neural signals_  \n  A standardized communication flow between memory, agents, and logic evaluators.\n\nThis separation enables modular development, autonomous behavior, and semantic reflection — one layer at a time.\n\nBelow is a high-level architecture diagram and description of each core component and how they interact:\n\n![Inception ICORE Architecture](./docs/images/inception-graph.png)\n\n### BaseAgent \u0026 Sentience DSL\n\n- **BaseAgent** (`agents/agent.rs`):\n\n  - Maintains an in-process context (`Context`) for simple “remember/recall/if context includes” logic.\n  - Loads and executes Sentience DSL code directly using the `sentience` crate.\n  - During `handle`, DSL memory is seeded from global stores and flushed back after execution.\n\n\n### Memory Layers\n\n1. **Short-Term Memory** (`memory/short_term.rs`):\n\n   - In-memory `HashMap\u003cString, String\u003e`.\n   - Fast read/write for transient key-value pairs.\n   - Volatile (lost on server restart).\n\n2. **Long-Term Memory** (`memory/long_term.rs`):\n\n   - SQLite-backed key-value store (via [`sqlx`](https://github.com/launchbadge/sqlx)).\n   - Persistent on disk (`memory.db`).\n   - Async `get`, `set`, and `all` operations.\n\n3. **Latent Memory** (`memory/latent.rs`):\n   - Interfaces with ChromaDB REST API for vector embeddings and similarity search.\n   - Provides methods:\n     - `embed(id: \u0026str, vector: Vec\u003cf32\u003e)` → stores a dummy or computed embedding under `id`.\n     - `query(vector: Vec\u003cf32\u003e)` → returns a list of `(id, score)` pairs.\n   - In this prototype, embeddings are dummy zero-vectors (`vec![0.0; 1536]`), but you can replace with real LLM encoder outputs.\n\n### LLM Integration\n\n- The server expects an environment variable `LLM_URL` pointing to a local LLM HTTP server (e.g., [llama.cpp server](https://github.com/ggerganov/llama.cpp)).\n- Chat fallback logic (in `handlers/chat`) calls:\n  ```rust\n  model::generate(\u0026payload.message).await\n  ```\n\nwhich sends an HTTP request to `LLM_URL` with JSON `{ \"prompt\": \"...\"} ` and returns the generated text.\n\n### HTTP API (Axum)\n\n- Uses [Axum v0.7](https://github.com/tokio-rs/axum) with Tokio runtime.\n- Routes defined in `api/routes.rs` and handlers in `api/handlers.rs`.\n- All endpoints respond with JSON or `(StatusCode, String)` combos (converted via `impl IntoResponse`).\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n1. **Rust toolchain**\n\n   - Install [rustup](https://rustup.rs/) and ensure you have a recent stable toolchain:\n\n     ```bash\n     rustup update stable\n     rustup default stable\n     ```\n\n2. **Docker \u0026 Docker Compose** (for full development setup)\n\n   - [Docker Desktop](https://www.docker.com/products/docker-desktop) or Docker Engine v20+\n   - Docker Compose v1.29+ (or v2 integrated in Docker CLI)\n\n3. **Ports**\n\n   - **ChromaDB**: `8000`\n   - **LLM Server**: `11434`\n   - **ICORE Server**: `8080`\n\n---\n\n### Clone \u0026 Build\n\n```bash\ngit clone https://github.com/your-org/inception-ICORE-server.git\ncd inception-ICORE-server\n```\n\nYou can verify that the project builds locally:\n\n```bash\ncargo build\n```\n\n### Clone Sentience Dependency\n\nThis project depends on a local Rust crate named [`sentience`](https://github.com/nbursa/sentience).\n\nClone it into the **same parent directory** as this project:\n\n```bash\ngit clone https://github.com/nbursa/sentience.git\n```\n\n---\n\n### Environment Variables\n\nCreate a `.env` file in project root or export the following in your shell:\n\n```bash\n# .env (for Docker Compose or local development)\nCHROMADB_URL=http://localhost:8000\nCHROMA_COLLECTION_ID=\u003cyour-collection-uuid\u003e\nLLM_URL=http://localhost:11434\nICORE_ENV=development         # or \"production\"\nRUST_LOG=info               # e.g. \"debug\", \"info\", \"warn\", etc.\n\n# For Docker Compose (network aliases):\n# CHROMADB_URL=http://chromadb:8000\n# LLM_URL=http://llm:11434\n```\n\n- `CHROMADB_URL`\n  URL where ChromaDB is reachable (e.g., `http://localhost:8000`).\n\n- `CHROMA_COLLECTION_ID`\n  UUID of the ChromaDB collection used for vector storage. This must exist or be created separately.\n\n- `LLM_URL`\n  Base URL of your LLM service (e.g., local llama.cpp server on `:11434`).\n\n- `ICORE_ENV`\n  Controls environment mode (`development` or `production`). Affects logging levels, etc.\n\n- `RUST_LOG`\n  Standard [`tracing_subscriber`](https://docs.rs/tracing-subscriber) filter (e.g. `info`, `debug`).\n\n---\n\n### Running with Docker Compose\n\nA ready-made `docker-compose.dev.yml` orchestrates:\n\n- **chromadb** service\n- **llm** (local Llama server)\n- **ICORE-server** (this Rust application)\n\n1. Ensure you have a valid `CHROMA_COLLECTION_ID`. If not, you must create a collection in ChromaDB first (via its HTTP API or UI).\n\n2. In the project root (where `docker-compose.dev.yml` lives), run:\n\n   ```bash\n   docker-compose -f docker-compose.dev.yml up -d --build\n   ```\n\n   This will:\n\n   - Pull/build the `chromadb/chroma:0.6.3` image and expose port `8000`.\n   - Build the local LLM container (`Dockerfile.server` in `llama.cpp/`) and expose port `11434`.\n   - Build the ICORE Server container (`Dockerfile` in project root) and expose port `8080`.\n\n3. Verify all services are healthy:\n\n   ```bash\n   docker-compose -f docker-compose.dev.yml ps\n   ```\n\n4. Test the ICORE server:\n\n   ```bash\n   curl -i http://localhost:8080/api/ping\n   # Expected: HTTP/1.1 200 OK, Body: \"pong\"\n   ```\n\nTo stop and remove all containers:\n\n```bash\ndocker-compose -f docker-compose.dev.yml down\n```\n\n---\n\n### Running Locally without Docker\n\nIf you prefer to run everything natively:\n\n1. **Start ChromaDB**\n\n   - Download \u0026 run ChromaDB:\n\n     ```bash\n     docker run -d --name chroma-local \\\n       -p 8000:8000 \\\n       -e IS_PERSISTENT=FALSE \\\n       -e ANONYMIZED_TELEMETRY=FALSE \\\n       chromadb/chroma:0.6.3\n     ```\n\n   - Create a collection (use Postman/cURL or ChromaDB UI) and note its UUID.\n\n2. **Start LLM Server** (e.g., llama.cpp)\n\n   - Navigate to `./llama.cpp/` (ensure `Dockerfile.server` is configured).\n   - Build \u0026 run:\n\n     ```bash\n     docker build -t llama-server -f Dockerfile.server .\n     docker run -d --name llama-server -p 11434:11434 llama-server \\\n       --model /models/mistral-7b-q4.gguf \\\n       --port 11434 --ctx-size 256 --threads 1\n     ```\n\n3. **Configure `.env`** (in project root):\n\n   ```bash\n   CHROMADB_URL=http://localhost:8000\n   CHROMA_COLLECTION_ID=\u003cyour-collection-uuid\u003e\n   LLM_URL=http://localhost:11434\n   ICORE_ENV=development\n   RUST_LOG=info\n   ```\n\n4. **Run ICORE Server**\n\n   ```bash\n   cargo run\n   ```\n\n   The server will:\n\n   - Initialize `ShortTermMemory` (in-memory).\n   - Initialize `LongTermMemory` (SQLite file `memory.db`).\n   - Initialize `LatentMemory` (ChromaDB client to given URL).\n   - Attempt to load `agent.sent` from project root (if present).\n   - Start listening on `0.0.0.0:8080`.\n\n---\n\n### Testing the Server\n\n**Health Check**\n\n```bash\ncurl -i http://localhost:8080/health\n# 200 OK\n# Body: ICORE server is healthy.\n```\n\n**Ping**\n\n```bash\ncurl -i http://localhost:8080/api/ping\n# 200 OK\n# Body: pong\n```\n\n**Short-Term Memory**\n\n```bash\n# Set a value\ncurl -i -X POST http://localhost:8080/api/mem/short/my_key \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"value\":\"hello\"}'\n# 200 OK, Body: stored\n\n# Get the value\ncurl -i http://localhost:8080/api/mem/short/my_key\n# 200 OK, Body: hello\n```\n\n**Long-Term Memory**\n\n```bash\n# Set (async behind scenes)\ncurl -i -X POST http://localhost:8080/api/mem/long/user123 \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"value\":\"persistent data\"}'\n\n# Get value\ncurl -i http://localhost:8080/api/mem/long/user123\n# 200 OK, Body: persistent data\n```\n\n**Latent Memory (ChromaDB)**\n\n```bash\n# Embed dummy vector under “doc1”\ncurl -i -X POST http://localhost:8080/api/mem/latent/embed \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"id\":\"doc1\",\"content\":\"some text to embed\"}'\n# 200 OK, Body: embedded\n\n# Query with dummy vector\ncurl -i -X POST http://localhost:8080/api/mem/latent/query \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"content\":\"any text\"}'\n# 200 OK, Body: [\"doc1\", ...]  (list of nearest IDs)\n```\n\n**Chat \u0026 Sentience**\n\n```bash\n# Chat endpoint (JSON)\ncurl -i -X POST http://localhost:8080/api/chat \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\":\"remember color = blue\"}'\n# 200 OK, Body: \"Okay, remembered color = blue\"\n\ncurl -i -X POST http://localhost:8080/api/chat \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\":\"recall color\"}'\n# 200 OK, Body: \"color = blue\"\n\ncurl -i -X POST http://localhost:8080/api/chat \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"message\":\"What is the meaning of life?\"}'\n# 200 OK, Body: \u003cLLM‐generated text\u003e (fallback if no DSL match)\n\n# Direct Sentience DSL execution (execute code snippet immediately)\ncurl -i -X POST http://localhost:8080/api/sentience/run \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"code\":\"on input(hi) { mem.short[\\\\\"response\\\\\"] = \\\\\"Hello from DSL!\\\\\" }\"}'\n# 200 OK, Body: {\"output\":\"\"}  (empty unless DSL code sets a return)\n```\n\n---\n\n## Configuration \u0026 Environment Variables\n\n| Variable               | Description                                                                                     | Default / Example                      |\n| ---------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------- |\n| `CHROMADB_URL`         | URL of ChromaDB HTTP API (e.g., `http://localhost:8000`).                                       | `http://localhost:8000`                |\n| `CHROMA_COLLECTION_ID` | UUID of the ChromaDB collection for storing/querying embeddings. Must exist beforehand.         | `1414cedf-3081-4235-ab29-656549bdff1a` |\n| `LLM_URL`              | Base URL for the LLM service (used for fallback text generation).                               | `http://localhost:11434`               |\n| `ICORE_ENV`            | Environment mode (`development` or `production`). Controls logging/filtering and optimizations. | `development`                          |\n| `RUST_LOG`             | Logging filter for [`tracing_subscriber`](https://docs.rs/tracing-subscriber). (e.g. `info`).   | `info`                                 |\n| `DATABASE_URL`         | (Optional) SQLite file path for long-term memory (used by `sqlx`). Defaults to `memory.db`.     | `memory.db`                            |\n| `AGENT_SENT_FILE`      | (Optional) Path to a Sentience DSL script (defaults to `agent.sent` in project root).           | `./agent.sent`                         |\n\n\u003e **Note:**\n\u003e\n\u003e - If environment variables are missing, the server will panic on startup.\n\u003e - Always ensure `CHROMA_COLLECTION_ID` matches an existing ChromaDB collection ID.\n\n---\n\n## API Reference\n\nAll endpoints are under the `/api` prefix (except `/health`).\n\n### 1. Health Check\n\n```\nGET /health\n```\n\n- **Response**\n\n  - `200 OK`\n  - Body: plain text `\"ICORE server is healthy.\"`\n\n### 2. Short-Term Memory Endpoints\n\n#### 2.1. Get Short-Term Value\n\n```\nGET /api/mem/short/:key\n```\n\n- **Path Parameters**\n\n  - `:key` (string) – key to retrieve.\n\n- **Responses**\n\n  - `200 OK` + body containing the stored string value.\n  - `404 Not Found` + body `\"key not found\"` if the key is missing.\n\n- **Example**\n\n  ```bash\n  curl -i http://localhost:8080/api/mem/short/foo\n  ```\n\n#### 2.2. Set Short-Term Value\n\n```\nPOST /api/mem/short/:key\nContent-Type: application/json\n\n{\n  \"value\": \"\u003cstring\u003e\"\n}\n```\n\n- **Path Parameters**\n\n  - `:key` (string) – key to set.\n\n- **Request Body**\n\n  ```json\n  {\n    \"value\": \"some text\"\n  }\n  ```\n\n- **Responses**\n\n  - `200 OK` + body `\"stored\"` (always).\n\n- **Example**\n\n  ```bash\n  curl -i -X POST http://localhost:8080/api/mem/short/foo \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"value\":\"bar\"}'\n  ```\n\n### 3. Long-Term Memory Endpoints\n\n#### 3.1. Get Long-Term Value\n\n```\nGET /api/mem/long/:key\n```\n\n- **Path Parameters**\n\n  - `:key` (string) – key to retrieve.\n\n- **Responses**\n\n  - `200 OK` + body containing the stored string value.\n  - `404 Not Found` + body `\"key not found\"` if the key is missing.\n\n- **Example**\n\n  ```bash\n  curl -i http://localhost:8080/api/mem/long/user123\n  ```\n\n#### 3.2. Set Long-Term Value\n\n```\nPOST /api/mem/long/:key\nContent-Type: application/json\n\n{\n  \"value\": \"\u003cstring\u003e\"\n}\n```\n\n- **Path Parameters**\n\n  - `:key` (string) – key to set.\n\n- **Request Body**\n\n  ```json\n  {\n    \"value\": \"persistent data\"\n  }\n  ```\n\n- **Responses**\n\n  - `200 OK` + body `\"stored\"` (always).\n\n- **Example**\n\n  ```bash\n  curl -i -X POST http://localhost:8080/api/mem/long/user123 \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"value\":\"persistent data\"}'\n  ```\n\n### 4. Latent Memory (ChromaDB) Endpoints\n\n#### 4.1. Embed Vector\n\n```\nPOST /api/mem/latent/embed\nContent-Type: application/json\n\n{\n  \"id\": \"\u003cstring\u003e\",\n  \"content\": \"\u003cstring\u003e\"\n}\n```\n\n- **Request Body**\n\n  - `id` (string) – unique identifier for the document/embedding.\n  - `content` (string) – raw text whose embedding is stored.\n  - **Note**: In the current prototype, the handler constructs a dummy zero‐vector of length 1536. You can modify `embed_latent` to call a real embedding service.\n\n- **Responses**\n\n  - `200 OK` + body `\"embedded\"` if successful.\n  - `500 Internal Server Error` + body `\"error\"` on failure.\n\n- **Example**\n\n  ```bash\n  curl -i -X POST http://localhost:8080/api/mem/latent/embed \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"id\":\"doc1\",\"content\":\"something to embed\"}'\n  ```\n\n#### 4.2. Query Nearest IDs\n\n```\nPOST /api/mem/latent/query\nContent-Type: application/json\n\n{\n  \"content\": \"\u003cstring\u003e\"\n}\n```\n\n- **Request Body**\n\n  - `content` (string) – raw text whose embedding is used for similarity search (currently converted to dummy zero‐vector).\n\n- **Responses**\n\n  - `200 OK` + JSON array of matching IDs (`Vec\u003cString\u003e`) ordered by descending similarity (highest score first).\n  - `500 Internal Server Error` + plain text error message if ChromaDB query fails.\n\n- **Example**\n\n  ```bash\n  curl -i -X POST http://localhost:8080/api/mem/latent/query \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"content\":\"search terms\"}'\n  ```\n\n### 5. Chat Endpoint\n\n```\nPOST /api/chat\nContent-Type: application/json\n\n{\n  \"message\": \"\u003cstring\u003e\"\n}\n```\n\n- **Request Body**\n\n  - `message` (string) – user’s chat input.\n\n- **Behavior**\n\n  1. If a **Sentience DSL** is loaded, constructs DSL code snippet:\n\n     ```\n     on input(\u003cmessage\u003e) { … }\n     ```\n\n     – The agent executes this snippet via its built-in DSL engine.\n     – After execution, checks if DSL wrote a `\"response\"` key in its internal short memory. If so, returns that as the response.\n\n  2. If DSL didn’t produce a response (or DSL isn’t loaded):\n\n     - Checks for `remember `, `recall `, or `if context includes ` commands for BaseAgent logic.\n     - Otherwise, falls back to LLM: calls `model::generate(message).await`, returning the generated text.\n\n- **Response**\n\n  - `200 OK` + JSON string with the agent’s reply.\n\n- **Example**\n\n  ```bash\n  # Remember example\n  curl -i -X POST http://localhost:8080/api/chat \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"message\":\"remember mood = happy\"}'\n\n  # Recall example\n  curl -i -X POST http://localhost:8080/api/chat \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"message\":\"recall mood\"}'\n\n  # Generic question (LLM fallback)\n  curl -i -X POST http://localhost:8080/api/chat \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"message\":\"Tell me a joke.\"}'\n  ```\n\n### 6. Sentience DSL Endpoint\n\n```\nPOST /api/sentience/run\nContent-Type: application/json\n\n{\n  \"code\": \"\u003cSentience DSL code\u003e\"\n}\n```\n\n- **Request Body**\n\n  - `code` (string) – raw Sentience DSL snippet to execute immediately (without `on input(...)`).\n\n- **Behavior**\n\n  - The agent executes the provided `code` snippet using its internal DSL engine.\n  - Returns whatever the DSL code returned (if any) or an empty string if nothing was returned.\n\n- **Response**\n\n  - `200 OK` + JSON:\n\n    ```json\n    {\n      \"output\": \"\u003cstring\u003e\"\n    }\n    ```\n\n    - `output` may be empty (`\"\"`) if DSL script didn’t explicitly set a value.\n\n- **Example**\n\n  ```bash\n  curl -i -X POST http://localhost:8080/api/sentience/run \\\n    -H \"Content-Type: application/json\" \\\n    -d '{\"code\":\"on startup() { mem.short[\\\\\"greeting\\\\\"] = \\\\\"Hello from DSL!\\\\\" }\"}'\n  ```\n\n---\n\n## Agent DSL (“Sentience”) Details\n\n**Sentience DSL** allows you to define event‐driven logic in a simple, internal scripting language. Typical patterns:\n\n1. **Loading DSL at Startup**\n\n   - Place your DSL file as `agent.sent` in project root or specify via environment variable.\n   - On server startup, `main.rs` does:\n\n     ```rust\n     if let Ok(sent_code) = fs::read_to_string(\"agent.sent\") {\n         base_agent.load_sentience(\u0026sent_code)?;\n         println!(\"Loaded Sentience DSL from agent.sent\");\n     }\n     ```\n\n2. **DSL Grammar (Example)**\n\n   ```sentience\n   // Defines behavior on input event\n   on input(user_msg) {\n       if user_msg == \"ping\" {\n           mem.short[\"response\"] = \"pong from DSL\";\n       } else if user_msg startswith \"set \" {\n           // parse \"set key=value\"\n           let kv = split(user_msg[4..], \"=\");\n           mem.short[kv[0]] = kv[1];\n       }\n   }\n\n   // Defines behavior on startup\n   on startup() {\n       mem.short[\"welcome\"] = \"Welcome, dear user!\";\n   }\n   ```\n\n3. **Memory Access in DSL**\n\n   - `mem.short[\u003ckey\u003e] = \u003cvalue\u003e` reads/writes short-term memory.\n   - `mem.long[\u003ckey\u003e] = \u003cvalue\u003e` reads/writes long-term memory (SQLite).\n   - The agent seeds both memories when handling code and flushes updates after execution.\n\n4. **Sending Responses**\n\n   - To return a chat response via DSL, set `mem.short[\"response\"] = \"\u003csome text\u003e\"`.\n   - After DSL runs, the handler checks `guard.inner.get_short(\"response\")` and returns it if non-empty.\n\n5. **Building a DSL File**\n\n   - Create `agent.sent` in project root.\n   - Follow your DSL grammar (consult `sentience` crate docs for precise syntax).\n\n---\n\n## Directory Structure\n\n```\ninception-ICORE-server/\n├── Cargo.toml\n├── Dockerfile\n├── docker-compose.dev.yml\n├── docker-compose.prod.yml\n├── README.md\n├── agent.sent            # (optional) Sentience DSL script\n├── memory.db             # SQLite database (auto-created on first run)\n├── src/\n│   ├── main.rs           # Entry point: initializes mem, agent, starts Axum server\n│   ├── config/           # Configuration loading (env, Settings struct)\n│   │   └── settings.rs\n│   ├── agents/\n│   │   ├── agent.rs      # BaseAgent implementation \u0026 DSL integration\n│   │   └── mod.rs        # Re-exports AGENT, BaseAgent, SentienceAgent\n│   ├── api/\n│   │   ├── routes.rs     # Defines Axum router \u0026 endpoints\n│   │   ├── handlers.rs   # Endpoint handlers (ping, memory, chat, etc.)\n│   │   └── mod.rs\n│   ├── memory/\n│   │   ├── short_term.rs # In-memory key-value store\n│   │   ├── long_term.rs  # SQLite-backed key-value store\n│   │   ├── latent.rs     # ChromaDB client for embeddings \u0026 queries\n│   │   └── mod.rs\n│   ├── ICORE/\n│   │   ├── model.rs      # LLM HTTP client \u0026 `generate(prompt)` function\n│   │   └── context.rs    # Context for BaseAgent (“remember/recall/if context includes”)\n│   │   └── protocol.rs   # ICORE protocol definitions (errors, etc.)\n│   │   └── mod.rs\n│   ├── config.rs?        # top-level config module for env/settings\n│   └── ...               # other modules (utilities, etc.)\n└── llama.cpp/            # (submodule) Llama.cpp code \u0026 Dockerfile for local LLM server\n    ├── Dockerfile.server\n    └── ...\n```\n\n---\n\n## Logging \u0026 Monitoring\n\n- Uses [`tracing`](https://docs.rs/tracing) and [`tracing_subscriber`](https://docs.rs/tracing-subscriber) for structured logging.\n- Log level controlled by `RUST_LOG` environment variable (e.g., `info`, `debug`, `warn`).\n- In development, set `RUST_LOG=debug` to see detailed request/response and SQL queries.\n- Logs are printed to stdout by default (suitable for Docker).\n\n---\n\n## Development Workflow\n\n1. **Code Formatting \u0026 Linting**\n\n   ```bash\n   rustup component add rustfmt clippy\n   cargo fmt --all\n   cargo clippy --all -- -D warnings\n   ```\n\n2. **Running Tests**\n   If/when unit/integration tests are added:\n\n   ```bash\n   cargo test\n   ```\n\n3. **Adding a New Endpoint**\n\n   1. Define route in `src/api/routes.rs`.\n   2. Implement handler in `src/api/handlers.rs`.\n   3. Update any relevant memory/agent logic.\n   4. Add a curl example in README for documentation.\n\n4. **Extending Memory Layer**\n\n   - **Short-Term**: Modify `memory/short_term.rs` to change in-memory storage.\n   - **Long-Term**: Change SQLite schema or switch to Postgres by updating `LongTermMemory` and `DATABASE_URL`.\n   - **Latent**: Update `memory/latent.rs` to call a real embedding service instead of dummy.\n\n5. **Updating the DSL Script**\n\n   - Edit `agent.sent` at project root.\n   - Reload server or send a direct `POST /api/sentience/run` to test new logic.\n\n---\n\n## Contributing\n\nContributions are welcome! Please follow these guidelines:\n\n1. Fork the repository.\n2. Create a feature branch:\n\n   ```bash\n   git checkout -b feature/my-new-feature\n   ```\n\n3. Commit your changes with clear, descriptive messages.\n4. Run formatting \u0026 lints:\n\n   ```bash\n   cargo fmt --all\n   cargo clippy --all -- -D warnings\n   ```\n\n5. Add/update tests if applicable.\n6. Push to your fork and open a Pull Request on GitHub.\n\nPlease ensure all CI checks (formatting, linting, tests) pass before requesting review.\n\n---\n\n## License\n\n⚠️ **Note**: This project is still in an experimental phase and is not guaranteed to be stable or production-ready.\n\nThis project is licensed under a **Proprietary Non-Commercial License**.  \nIt is free to use for research, education, and experimentation, but **commercial use is strictly prohibited without written permission**.  \nSee [LICENSE](LICENSE) for full terms.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnbursa%2Finception-core-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnbursa%2Finception-core-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnbursa%2Finception-core-server/lists"}