Concepts
Workspaces and projects
Organize access and subject matter, bind folders, manage indexing and history, synchronize machines, and repair duplicate or stale project records.
Workspaces
A workspace is the outer sharing boundary, even when you are its only member. Use one for a personal project, a product, a team, or client work that must stay separate. Memory, documents, and tickets live inside it; role, project, and personal scope still decide which records each authorized person can read or change.
Your account can belong to several, and personal work can live in its own.
A workspace can be created empty or bootstrapped with a folder, an initial project, indexing, and generated editor instructions. Workspace administrators can inspect membership and, on supported team plans, configure how several machines contribute index updates.
Projects
A project is one body of work inside a workspace — usually one repository. Memory is recorded against a project, so decisions about the API service don't surface while you're working on the marketing site.
Some records can be workspace-wide on purpose. Preferences and skills carry their own account, workspace, or project scope, while a shared record saved without a project belongs to the workspace rather than one repository.
Projects also own the indexed-file and code-graph boundary. Their overview, statistics, file list, index status, index history, and recent Git changes are different views of the same body of work.
How a folder becomes a project
The first time you work in a folder, it's bound to a project. From then on it resolves on its own — no flags, no arguments. A new folder offers to create one.
Connected assistants use the folder binding when it is unambiguous and should ask you to choose when it is not. You can always ask "what workspace and project am I in?" To change the persistent binding, rerun setup in that folder or update the association in the dashboard.
Indexing and file history
An initial local ingest validates the folder, creates or resolves the project, and sends eligible files for indexing. Later refreshes update changed files. You can inspect:
- whether an index exists, how fresh it is, and whether a refresh is running;
- the files currently represented in the project;
- index history by time, branch, or contributing machine;
- recent repository changes;
- project-level statistics and overview information.
A hosted gateway cannot read an arbitrary folder on your computer. When it reports that local ingest is required, let the installed local sync path or ContextStream Desktop handle the folder. Repeating the hosted request cannot grant it filesystem access.
More than one machine
Team workspaces can control whether multiple approved machines contribute index updates, which machines are allowed, and how branch conflicts are resolved. Available branch policies can prefer the default branch, the newest update, or a feature branch; conflict handling can prefer timestamps, the default branch, or manual resolution.
The safest policy depends on the workspace. A production documentation project usually wants the default branch to remain authoritative. A feature-heavy engineering workspace may deliberately prefer the newest or active feature branch.
One person, three checkouts, one body of knowledge
You work on the same repository from a laptop, a desktop, and a feature checkout. Those checkouts can resolve to one canonical project, so the decision you recorded on the laptop and the runbook you updated on the desktop stay with the same body of work.
The checkouts are still distinct sources of file freshness. The feature checkout may contain changes the default branch does not, and a hosted gateway cannot infer those uncommitted files from the project record. The local sync path validates each checkout and contributes eligible changes according to the workspace's branch policy.
ContextStream does not trust a filesystem path as permanent identity. If a repository is deleted and an unrelated checkout later appears at the same path, the replacement should not silently inherit the old project's content mapping. Reconnect or bind the new checkout deliberately.
This is useful when you work alone; team controls add governance for which machines and branches may contribute. They are not required for cross-session memory or for binding several of your own checkouts to one project.
Repairing project records
Several operations sound similar but have very different effects:
| Need | What to do |
|---|---|
| Two project records represent the same work | Merge or combine the duplicate into the project you intend to keep |
| One indexed file should disappear | Remove that exact path from the project index |
| The entire index should be rebuilt or removed | Purge the indexed files and vectors while keeping the project record |
| This machine should stop treating a folder as this project | Forget the local mapping; server-side project data stays intact |
| The project itself should no longer exist | Delete the project only after verifying the exact target |
These are destructive at different layers. Check the workspace, project ID, folder, and path list before changing them. Removing an index is not the same as deleting source files from disk.
Getting it wrong
Two symptoms, one cause:
Nothing relevant surfaces. You're in the wrong project — memory is there, scoped somewhere else.
Irrelevant things surface. Two repositories are bound to one project. Split them.
Confirming the current scope and repairing the folder binding fixes both.
Monorepos
One project for the whole repository is usually right — the code shares history, and that's what memory follows. Split into several when the parts have genuinely separate ownership, access boundaries, or decisions that shouldn't cross-contaminate.
When the repository root contains several intentionally separate ContextStream projects, initialize from the parent and select the child project for a project-scoped write. Do not guess from a similar folder name.
If it doesn't work
The wrong project resolved. Select the intended project for the current request, then repair the folder binding through setup or the dashboard.
I need to record something workspace-wide. Say so explicitly — "remember for the whole workspace that…". Preferences and skills can also be saved at account, workspace, or project scope.
A teammate can't see what I recorded. Different workspace, or it was recorded in a personal scope. See Working as a team.
A new file is missing but old files search correctly. The existing index is usable but behind the working tree. Refresh or run the local ingest path, then retry the narrow search.
Two projects have split the same history. Inspect both records, choose the one to keep, then merge or combine them. Do not delete either before confirming where its memory and index data will land.
This computer keeps re-indexing an old checkout. Remove the local mapping for that exact folder. Purging the server index alone does not stop a still registered machine from contributing again.