# Recon documentation

> What Recon Local is, what it remembers, and where to begin.

Recon Local is private work memory for one person on a Mac. It connects the material you already have with the decisions and reasoning created while you work, then gives that context back to you and supported AI tools later.

## What problem it solves

Files usually preserve **what shipped**. They rarely preserve why an approach was chosen, what failed before it, which constraint mattered, or when the choice should be revisited. That missing reasoning forces you and your AI tools to rediscover the same context.

Recon keeps the durable parts together:

- the source or artifact
- the decision and its reason
- rejected or failed approaches
- corrections and lessons
- the condition for revisiting a choice
- receipts showing where each part came from

Recon is not a passive transcript recorder and does not silently copy every Claude Code or Codex conversation.

## The shortest useful path

1. [Install Recon and choose one source](/help/getting-started).
2. Let Recon form source-backed [Knowledge](/help/knowledge-and-work).
3. Connect Claude Code or Codex in **Settings > AI tools**.
4. Work normally with the installed Recon guidance.
5. [Ask Recon](/help/ask) about the decision later and open its receipts.

## Choose the page you need

- **New to Recon:** [Getting started](/help/getting-started)
- **Want the mental model:** [How Recon works](/help/how-recon-works)
- **Unsure about Knowledge and Work:** [Knowledge and Work](/help/knowledge-and-work)
- **Want practical questions to try:** [Use cases](/help/use-cases)
- **Need the Terminal command:** [AI tools and CLI](/help/ai-tools-and-cli)
- **Need a fix:** [Troubleshooting](/help/troubleshooting)
- **Evaluating shared memory:** [Cloud and Teams](/help/cloud-and-teams)

> Recon Local is the available free, local product. Cloud and Teams use a separate hosted memory boundary. The Local app does not silently synchronize its database with a hosted workspace.

---

# Getting started

> Install Recon Local, add a source, connect an AI tool, and verify the first answer.

You can use the Mac app without Terminal. Start with one small, useful source so the first result is easy to inspect.

## Requirements

- Apple Silicon Mac
- macOS 12 or later
- Claude Code, Codex, the Codex app, ChatGPT with bundled Codex, or a supported provider API key for model-backed work

## Install the app

1. Download the current release from [askrecon.com/download/mac](/download/mac).
2. Open the DMG and drag Recon into **Applications**.
3. Launch Recon from Applications, not from inside the DMG.
4. Complete the privacy and AI-tool checks in onboarding.

The public build is Developer ID signed, notarized by Apple, and stapled. Do not remove quarantine attributes or bypass Gatekeeper in Terminal. If macOS blocks a copy, download it again from the first-party link and follow [Troubleshooting](/help/troubleshooting).

## Add the first source

Choose one project, folder, or small set of documents. Recon shows the exact boundary before you confirm it. It skips common dependencies, generated output, secret-looking files, and unsupported formats.

During the first update, Recon saves completed work as it goes. A long source does not need to finish every global maintenance step before useful memory can appear.

## Connect an AI tool

Open **Settings > AI tools**. Automatic mode uses an available signed-in Claude Code or Codex installation. If nothing is ready, install and sign in to one supported tool or add a provider key, then select **Check again**.

Choose **Repair connection** if the tool is present but its Recon guidance or local memory tools are missing.

## Verify the result

Ask one question about work that actually exists in the selected source, for example:

> Why did we keep the first release local instead of hosted-only?

A useful answer should state the decision, explain the relevant constraint, and offer receipts. Open a receipt and verify that it points to material you selected.

If the source update completed but the answer is still missing, see [Troubleshooting](/help/troubleshooting#the-source-is-current-but-ask-cannot-answer).

---

# How Recon works

> The source, Knowledge, work-memory, and recall loop without database jargon.

Recon combines two things that are normally separated: what exists in your artifacts and what happened while you worked on them.

## 1. Sources provide the boundary

Recon reads only the folders and documents you confirm. Files are evidence, not a second copy of your entire filesystem. Raw events and exact live state should still come from their original systems.

## 2. Knowledge organizes what is current

Recon reads supported files in bounded batches, extracts source-backed facts, connects related topics, and forms a concise current view. The original receipts remain attached, including older information that was not used in the short summary.

Knowledge is a projection over evidence. It is not the only copy of your memory and can be rebuilt as organization improves.

## 3. Work preserves the reasoning

The installed Recon guidance asks a supported Claude Code or Codex session to retrieve relevant memory before it guesses. When a durable decision, rejection, correction, lesson, or revisit condition lands, the agent captures that specific result.

Recon does not save every message. It keeps the parts that should survive the session.

## 4. Recall returns a bounded answer

When you ask a question, Recon retrieves a small set of relevant local receipts. Your selected AI connection uses that context to form an answer. Follow-up questions use a bounded rolling conversation summary instead of resending an unlimited transcript.

A good answer can show:

- what was decided
- why it was decided
- what was tried or rejected
- what changed later
- when the choice should be revisited
- which file or work session supports each claim

## 5. You can inspect the system

Use **Knowledge** to inspect a topic and its connections. Use **Your Work** to inspect meaningful efforts and their sessions. Open receipts to verify the source. Use **Settings > AI usage** to see which model-backed operations ran and whether token counts are reported or estimated.

---

# Knowledge and Work

> What the two views mean and when to use each one.

Knowledge and Work answer different questions. Neither is a raw database browser.

## Knowledge

Knowledge answers: **What does Recon currently understand about this topic?**

Open a subject to see source-backed facts, decisions, related topics, where the information was learned, changes over time, and anything that needs review. Selecting a relationship narrows the view to the relevant connected information.

Knowledge is useful when you want to learn or revisit a topic without knowing which session or file contains the answer.

## Your Work

Your Work answers: **What meaningful effort happened, and how did Recon help?**

A Work item groups a real effort, such as fixing ingestion from git worktrees or preparing a local Mac release. It can include:

- Claude Code or Codex sessions
- decisions and rejected paths
- files and topics involved
- memory retrieved before the work
- new memory captured during the work
- the result and when it happened

Open **Your Work** from the top of Knowledge. Work is not a list of generic “work item 1” rows. Its title should describe the effort a person would recognize.

## Sessions

A session is one supported agent conversation inside a Work item. Ask conversations in the Mac app are separate from Claude Code or Codex work sessions, even when both use the same local memory.

## Needs review

Review appears when Recon finds a duplicate, conflict, uncertain merge, or other condition that needs a person. Open the item to compare the receipts and use the action shown there. A warning is not the same as a settled fact.

---

# Use cases and examples

> Practical questions that show the value of decision and work memory.

Recon is most useful after it has seen both an artifact and the reasoning around it. Use real work rather than a toy question.

## Return to an implementation decision

**Question:** Why did we use a signed-in CLI subprocess instead of an agents SDK?

The useful answer is not only the selected implementation. It should explain the authentication constraint, which SDK path was rejected, the cost or trade-off of the subprocess, and which change would make the decision worth revisiting.

## Avoid repeating a failed approach

**Question:** What did we already try before fixing the first-message loading state?

Recon can return the failed path and why it did not solve the user-visible problem, so a new session does not recommend the same attempt again.

## Understand a production guard

**Question:** Why does Recon block ingestion from a linked git worktree?

The answer can connect the guard in code to the earlier duplication or database problem, the ticket that introduced it, and the work session that verified the fix.

## Revisit a choice when its condition changes

**Question:** Which local-only decisions should we revisit now that a team needs shared memory?

Revisit conditions stay attached to their decisions. Recon can surface them when you ask. Recon Local does not currently run a proactive reminder inbox that checks every revisit condition for you.

## Preserve non-code reasoning

If a selected document contains product research, customer notes, operating procedures, or a client decision, Recon can organize and recall it. Automatic in-session capture currently depends on supported Claude Code or Codex guidance, so do not assume every external meeting or app is recorded automatically.

## What makes a good first question

- Ask about a decision you personally remember making.
- Include the feature, incident, customer, or work area in the wording.
- Prefer “why,” “what changed,” “what did we reject,” or “when should we revisit” over a generic keyword search.
- Open at least one receipt before trusting the answer.

---

# Sources and updates

> What Recon can read, what it skips, and how source updates become Knowledge.

Sources define what Recon may read. Adding a folder is not permission to read the rest of your Mac.

## Supported material

Recon can read source code and common work documents, including Markdown, text, JSON, CSV, PDF, and DOCX. Very large or unsupported files may be skipped or bounded.

## What Recon skips

Recon excludes common dependency folders, generated build output, secret-looking files, and unsupported formats. It does not treat raw Claude transcript JSONL as a normal source folder. Historical transcript import needs a bounded, explicit importer so private conversation data is not swept in accidentally.

## What an update does

An update reads changed material in bounded batches, saves completed facts and receipts, connects related memory, and queues Knowledge organization. Work already saved remains available if a later model call is paused or fails.

Use **Settings > Sources** to:

- add a project, folder, or selected documents
- see update progress and errors
- update a source now
- pause, retry, or remove a source

Removing a source stops future reads. Existing derived memory remains until you explicitly remove the local data associated with it.

## Keeping a project current

Choose **Update now** after meaningful file changes. If you opt in, local git hooks can refresh changed files after pull, merge, or rebase. Recon never installs persistent hooks without your action.

Do not start a second ingest while the app or another Recon process is updating the local store. If Recon reports that memory is busy, let the current operation finish and retry.

---

# Ask and follow-up questions

> How answers are formed, how follow-ups keep context, and how to verify a response.

Ask is the fastest way to return to a decision or understand earlier work.

## What happens after you send a question

1. Recon retrieves a bounded set of relevant local Knowledge, Work, and receipts.
2. The selected Claude Code, Codex, or provider connection forms an answer from that context.
3. Recon presents the answer with structured sections and source receipts instead of an unbroken wall of text.

The first message should immediately appear in the conversation while Recon shows that it is looking into the question. It should not leave an empty response container that looks frozen.

## Follow-up context

Follow-ups remain in the same Ask conversation. Recon uses the current question, a bounded summary of the conversation, and newly retrieved memory. It does not send an unlimited transcript back through the model on every turn.

## Verify an answer

Open a receipt to see the supporting file, code, document, or work session. Treat a disputed item as an open question, not a settled fact. If the available receipts cannot support a complete answer, Recon should say that instead of filling the gap.

## Ask better questions

Good:

- Why did we choose this approach?
- What did we try and reject before this fix?
- What changed since the original decision?
- Which condition would make us revisit it?
- What earlier work should I know before changing this file?

Less useful:

- Tell me everything.
- What do you know?
- A keyword with no topic or work context.

Questions about decisions work best when the decision was captured by the Recon guidance or appears in a selected source.

---

# AI tools and CLI

> The difference between the Mac app, in-session memory tools, and the optional recon command.

The Mac app bundles the local runtime. You do not need an npm installation or a Terminal command to use the app.

## Connect Claude Code or Codex

Open **Settings > AI tools**. Recon can detect the Claude Code and Codex command-line tools, the Codex app, and ChatGPT's bundled Codex. A provider API key is an optional fallback.

Choose **Repair connection** to register the local memory tools and install current guidance.

## In-session memory tools

Supported agent sessions use three memory operations:

- `recon_context`: read relevant facts, prior decisions, rejected directions, and receipts before work
- `recon_capture`: save a durable decision, correction, rejection, lesson, or root cause when it lands
- `recon_finish`: close the Work session after you sign off

These are agent memory tools, not ordinary shell commands. They do not mean Recon records every message.

## Optional Terminal command

Choose **Install command line tool** in Settings if you want to run `recon` from new Terminal windows. This links the signed command bundled with the app; it does not install an npm package.

| Command | Use it for |
| --- | --- |
| `recon ingest [path]` | Build or refresh source memory for a project or selected path. |
| `recon context "question"` | Read relevant code facts, decisions, and receipts from Terminal. |
| `recon check [path]` | Find where agent instructions disagree with code or remembered decisions. |
| `recon fix [path]` | Prepare grounded corrections for stale agent-context files and ask before applying them. |
| `recon hooks install` | Opt in to git hooks that refresh changed files after pulls, merges, and rebases. |
| `recon skills status` | Check whether the Recon guidance is installed and current. |

The app and command read the same local store. Do not run overlapping ingests.

## Usage and budgets

Model-backed work uses the Claude Code, Codex, or provider account you choose. **Settings > AI usage** shows calls, model, timing, and reported or estimated tokens. Subscription tools do not expose a reliable dollar budget, so daily background limits use whole model calls.

---

# Privacy and local data

> What stays on the Mac, what reaches the selected model provider, and what diagnostics contain.

Local storage and model-provider calls are separate boundaries.

## What stays on this Mac

Selected sources, local memory, receipts, Ask conversations, Work, session metadata, paths, settings, and detailed usage history stay in the local Recon data folder, normally `~/.recon`.

## What can leave this Mac

During model-backed work, bounded source passages and questions go directly to the Claude Code, Codex, Anthropic, OpenAI, or Google account you selected. They are not proxied through a Recon model server.

If your selected provider processes a passage, that provider's account and data terms apply.

## Anonymous diagnostics

The Mac app waits for your explicit **Share diagnostics** choice during onboarding or in Settings. Diagnostics use a random install ID and bounded outcomes such as first open, source readiness, and Ask success.

Diagnostics never include:

- work or source content
- prompts or answers
- paths or file names
- memory text
- raw errors
- contact identity
- receipt or conversation IDs

Turn diagnostics off at any time. `DO_NOT_TRACK=1` and `RECON_TELEMETRY=off` also keep them off.

The public website uses a separate anonymous browser identity for page and download events. It is never joined to the Mac app's installation identity.

## Removing Recon

Moving Recon from Applications to the Trash removes the app but preserves local memory. Delete `~/.recon` only when you intentionally want to permanently remove the local store, settings, receipts, and history.

---

# Troubleshooting

> Fix AI detection, source updates, missing Knowledge, busy memory, and installation problems.

Keep completed work, use the visible retry path, and do not bypass macOS security controls.

## Recon cannot find Claude Code or Codex

Open **Settings > AI tools** and choose **Check again**. Confirm the tool is installed and signed in. Recon can detect the command-line tools, the Codex app, and ChatGPT's bundled Codex. If detection still fails, choose **Repair connection** or use a provider key.

## A source requires an AI tool or provider key

Source reading and Knowledge organization can require model-backed work. Connect one supported tool in **Settings > AI tools**, then retry the source. Recon should not mark onboarding complete as fully ready when no AI path is available.

## Recon asks for the main project folder

Linked git worktrees are intentionally blocked from normal ingestion because they can duplicate project memory and previously caused store problems. Select the main repository checkout instead.

## An update is busy, paused, or partly finished

Only one writer may update the local store at a time. Let the current ingest or maintenance run finish. Completed batches remain saved. A daily background limit can pause remaining model calls without discarding earlier work.

## The source is current but Ask cannot answer

Open **Knowledge** and check whether organization is still pending or failed. Retry the visible Knowledge action. The original facts and receipts remain in local memory even when the concise subject view has not formed yet.

## A source moved

Open **Settings > Sources**, remove the unavailable path, and add the new location. Removing a source does not silently delete all previously derived memory.

## The app will not open after download

Confirm the DMG came from [askrecon.com/download/mac](/download/mac). Delete the blocked copy, download it again, and compare its SHA-256 value with the [public release manifest](/download/mac/manifest). Do not run a quarantine-removal command.

## Send a useful support report

Email [support@askrecon.com](mailto:support@askrecon.com) with the release version, macOS version, visible error, action that triggered it, and whether Retry changed anything. Never send private source files, prompts, memory text, or API keys.

---

# Cloud and Teams

> How hosted and shared memory differ from Recon Local without blurring the storage boundary.

Recon Local, Cloud, and Teams share a product idea but not the same storage boundary.

## Local

Local is free private memory for one person on one Mac. Its PGlite store is authoritative for that installation. It reads selected local sources and works with the AI account you choose.

## Cloud

Cloud is one hosted authoritative memory for an individual who needs connectors, access beyond one Mac, or continuity across environments. It is not a hidden table-level synchronization between an unrelated Local database and a hosted database.

Hosted Recon already has connector infrastructure for systems such as Notion. The Local app does not yet bridge those hosted connectors into its private store.

## Teams

Teams uses the hosted substrate with multiple contributors, permissions, source receipts, and reconciliation when people or systems disagree. The value is shared reasoning: engineering can understand customer constraints, customer teams can understand technical trade-offs, and both can see why a decision changed.

## When to ask for access

Request Cloud or Teams when you need one of these:

- Notion or another hosted connector in the same memory
- access from multiple machines
- shared memory across contributors
- permissions and team-level source boundaries
- reconciliation of conflicting team or system evidence

[Contact Recon](/contact) with the sources, contributors, and workflow you need. Access is opened with early users based on real demand; the Local app does not pretend those connections are already active.