Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.copass.com/llms.txt

Use this file to discover all available pages before exploring further.

Ingestion is the act of feeding content into a sandbox. The chunking, entity extraction, and knowledge-graph wiring happens server-side — you just push the bytes through a data source and Copass takes care of the rest.

​
What you can do

  • Push a single string, file, or stdin stream as a one-shot ingest.
  • Index an entire project tree (full or incremental).
  • Watch a folder continuously — every save mirrors into the sandbox in seconds.
  • Install a background service so watching survives terminal closes.
“Ingest this folder of decision docs.” “Refresh the index for my project.”
For repeated automation, the CLI / SDK paths below are usually a better fit — ingestion is the kind of thing you script.

​
Via the CLI

# One-shot from stdin or a file
echo "Q3 pricing: enterprise tier bumps to $2k/seat" | \
  copass ingest --source-type decision

copass ingest path/to/notes.md

# Index a whole project
copass index                       # full
copass index --mode incremental    # only changed files

# Watch a folder continuously
copass watch                       # foreground; Ctrl-C to stop
copass watch install-service       # install as launchd/systemd; survives reboots
copass watch status                # is it running?
copass watch uninstall-service     # tear it down

​
Via the SDK

// One-shot ingest of inline text
await client.sources.ingest(sandboxId, dataSourceId, {
  text: 'Q3 pricing: enterprise tier bumps to $2k/seat starting 2026-04-01.',
  source_type: 'decision',
});
For folder watching, see the Filesystem driver — same wire endpoint, plus file fingerprinting so re-ingests stay incremental.

​
Source types

When ingesting text, you can tag it with a source_type so retrieval can filter or weight it:
source_typeUse for
text (default)Generic prose, notes, transcripts
decisionArchitecture decisions, RFCs, product calls
codeSource code (auto-detected from extension when ingesting files)
documentLong-form docs, design specs, contracts
eventTime-stamped events (incidents, releases, deploys)
If you don’t pass one, the server picks a sensible default based on content.

​
What happens after ingest

your push
   ↓
[ vault ]                    raw bytes, encrypted at rest, sandbox-prefixed
   ↓
[ chunking + extraction ]    splits into chunks, extracts entities + relationships
   ↓
[ knowledge graph ]          entities linked across data sources, scored, indexed
   ↓
ready for retrieval          discover / interpret / search now see your content
Ingestion is asynchronous — the API returns once the bytes are in the vault and the extraction job is queued. Retrieval becomes available within seconds for small payloads, longer for large folder indexes.

​
Advanced — direct vault writes

Beneath every ingest, content lands in the vault — Copass’s encrypted, sandbox-prefixed key/value store. Most users never need to touch it directly; ingest is the right entry point because it kicks off chunking and extraction. But if you have arbitrary blobs to store (binary assets, large encrypted snapshots, intermediate artifacts) that you don’t want extracted into the graph, you can write them straight to the vault: 
// Write a raw value at a path
await client.vault.put(sandboxId, 'snapshots/2026-04-29.bin', binaryData);

// Read it back
const data = await client.vault.get(sandboxId, 'snapshots/2026-04-29.bin');

// List, delete
await client.vault.list(sandboxId, { prefix: 'snapshots/' });
await client.vault.delete(sandboxId, 'snapshots/2026-04-29.bin');
The vault is sandbox-scoped, encrypted at rest under your sandbox’s prefix, and counts against your storage quota. Anything written here is not chunked or extracted — it’s just blobs. Use this for:
  • Large binary assets (images, PDFs, archives)
  • Encrypted snapshots and backups
  • Ephemeral intermediates between agent runs
For most content (text, decisions, code, docs), use ingest — extraction makes the content retrievable, the vault alone does not.

​
Common patterns

One-shot decision capture

Pipe Slack threads, meeting notes, or RFC drafts as --source-type decision. Retrieval surfaces them as first-class context.

Always-fresh project index

copass watch install-service mirrors a folder into your sandbox in real time. Agents see your latest code without you running a refresh.

CI-driven ingest

Add a step to your CI pipeline that pushes release notes, deploy events, or test results to a custom source. Audit the trail later via retrieval.

Bulk backfill

Initial loads of historical data — register a custom source with ingestion_mode: batch, push everything, then move to manual or polling for ongoing updates.

​
Next steps