cellin 0.3.0.dev2399675426601

Build long-lived multimodal memory, dream over it, and retrieve context with transparent weighting.

cellin

Cellin builds long-lived multimodal memory, dreams over it to consolidate ideas, and retrieves context with transparent weighted ranking.

Install

From source today:

git clone https://github.com/ben-ranford/cellin.git
cd cellin
make bootstrap

Install from PyPI:

python3 -m pip install cellin

Quickstart

From the repository root:

WORKSPACE=.cellin-workspace
python3 -m uv run cellin init --workspace "$WORKSPACE"
python3 -m uv run cellin ingest --config "$WORKSPACE/cellin.json" --input examples/starter/seed_envelopes.json
python3 -m uv run cellin retrieve --config "$WORKSPACE/cellin.json" --query "memory graph retrieval" --top-k 2
python3 -m uv run cellin dream --config "$WORKSPACE/cellin.json" --strategy abstraction
python3 -m uv run cellin eval run --suite smoke --config "$WORKSPACE/cellin.json" --output "$WORKSPACE/smoke.json"
python3 -m uv run cellin trace inspect --config "$WORKSPACE/cellin.json" --limit 5

See examples/starter/README.md for the same flow in a shorter checklist form.

Workspace config now supports role-specific storage backends:

{
  "runtime_id": "cellin-cli",
  "trace_path": "traces.jsonl",
  "profile_name": "balanced",
  "storage": {
    "memory": { "backend": "in_memory" },
    "graph": { "backend": "in_memory" },
    "vector": { "backend": "in_memory_vector_index" },
    "representation": { "backend": "in_memory_vector_index" }
  }
}

cellin init now writes this in-memory-first preset by default.

Legacy workspaces that only define database_path continue to work and are migrated to this shape behind the scenes.

For an explicit SQLite preset, set:

{
  "memory": { "backend": "sqlite", "database_path": "cellin.sqlite" },
  "graph": { "backend": "sqlite", "database_path": "cellin.sqlite" }
}

Primary surfaces

• CLI: cellin init, ingest, retrieve, dream, plugin list, eval run, trace inspect
• Ingestion: cellin.ingest.ArtifactEnvelope and cellin.ingest.CanonicalIngestor
• Retrieval: cellin.retrieval.WeightedRetriever, cellin.retrieval.RetrievalCandidateGenerator, and cellin.ranking.WeightedRanker
• Dreaming: cellin.dreaming.DreamRunner plus the built-in deduplication, abstraction, and contradiction-repair strategies
• Evals: cellin.evals.run_evaluation_suite and cellin.evals.run_smoke_eval
• Extensibility: cellin.runtime.PluginRegistry and the contracts exported from cellin.core