01 / Get ready
Choose where your knowledge lives.
PocketContext is one program containing a local server, a browser reader and a command-line client. Coding agents operate it using an installed skill; compatible chat apps connect through its optional MCP endpoint. You use your own agent and any model or tool subscriptions it requires.
The 0.23.1 release supports Linux amd64 and arm64, Apple Silicon Macs on macOS 15 or later, and Windows amd64. Start with the website setup prompt; your server’s agent generates a complete client prompt when you want to connect another computer. It checks the platform and asks only the questions needed for your choice.
Get the setup promptYour knowledge, on your phone
One link. Your own reader.
Ask your setup agent to make PocketContext available on a domain you control. It configures the same binary on an always-on host, checks the connection and gives you a secure sign-in link to open on your phone. PocketContext manages the HTTPS certificate and its renewal. No app, tunnel client or separate web server is needed on your phone.
You need a domain and a host reachable from the internet. Your agent checks these first and explains any missing DNS, router or hosting step. Local-only use remains the default. Keep the host running to read away from home.
Browse published pages, search your knowledge and inspect the sources behind a citation. Your external agent performs ingestion and synthesis through the CLI and installed skill. HTTPS hosting guide ↗
Your knowledge, your agent
Connect Gemini with one URL.
Ask your setup agent for MCP access on your PocketContext domain. It enables the endpoint in the same HTTPS service and checks the connection. You need an internet-reachable host that stays awake and online; no separate identity provider, agent runtime or private tunnel is required.
- Sign in to your PocketContext reader.
Your setup agent gives you a short-lived sign-in link. Open it in the same browser profile you use for Gemini web. You do not need to know the password generated during setup.
- Add your MCP URL in Gemini web.
In Settings → Connected Apps → Custom apps, add
https://your-domain/mcp. PocketContext handles client registration automatically; leave manually supplied client credentials empty. - Review and approve access.
Check the connection on PocketContext’s consent screen. If you need to sign in, open a fresh reader link in another tab of the same browser profile, then return to consent.
- Try a read, then confirm mobile access.
Select your connected app and ask it to list your spaces or find a published page. Then try the connection in Gemini mobile. Your setup agent records what worked and any pending checks.
MCP tools cover knowledge and space operations, including ingestion, extraction submission, staging and publication. They preserve citation and conflict checks. Server administration stays local. You can inspect and revoke connections at https://your-domain/oauth/connections.
Gemini account availability varies. Its attachment and voice capabilities do not automatically establish file transfer or tool support. After linking, test a read on your phone before relying on mobile access. Google’s custom-app guidance ↗ · PocketContext MCP guide ↗
Your knowledge, another computer
Read on your own computer.
Ask your knowledge base’s agent to connect another computer. It generates one client setup prompt containing an invitation. Copy that entire prompt from the server’s chat and paste it into the other computer’s agent. The agent installs the client if needed, checks the server’s identity, connects the tunnel and requests the signed-in reader on your desktop. If setup runs through SSH or on a machine without a usable desktop, it skips browser sign-in there and guides you to your own computer.
No separate invitation file or login code to copy. Sharing the invitation in your setup chats is part of this flow. If its one-time code expires during installation, keep the installed client and request a fresh invitation. The server and its tunnel must remain running; the client saves its connection and can restart its managed forward later.
A clear home for each project
Several knowledge bases. Choose by name.
Give each knowledge base a name such as “alpha” or “research.” Your agent’s router finds its matching skill and verifies the project before using it. Ask “ingest these notes in pocketcontext alpha” or “search alpha and research.” Results stay labelled, and evidence citations remain inside their knowledge base and space.
A knowledge base is a separate database; a space is a partition inside it. If a write does not name a knowledge base and you have not chosen a default, your agent asks before writing.
02 / The first useful thing
Turn two notes into one answer.
- Set up with your agent.
Copy a setup prompt, review it and paste it into an agent that can run commands on the intended computer. It will check the environment and report what it installed.
- Choose a small set of notes.
Try a project brief and meeting notes. Version 0.23.1 reads UTF-8 text itself: Markdown, TXT, CSV, JSON, RST, LOG, SRT and Org. It also keeps PDFs, images, audio and other files up to 50 MiB, which your agent converts to text.
- Ask for connected knowledge.
Have the agent read the imported sources, synthesize a page, attach citations and publish it. Importing a file alone does not create a published knowledge page.
- Ask a question and follow the evidence.
Open the reader to explore the page, its properties, revisions and cited passages. Tell the agent to flag conflicting or missing evidence instead of filling in the gaps.
“Read these two project notes. Create a short project overview with citations, highlight any conflicting dates, and publish it in PocketContext.”
The website examples are fictional. After setup, you can choose to import the PocketContext manual into its own space and try a cited backup guide, or use a clearly labelled synthetic example. Imported sources remain in the project’s history.
03 / Bring context together
Your tools provide the information.
Your agent makes the connection.
Your agent can collect accessible text from tools such as Notion, Evernote, Obsidian, Jira, ClickUp, HubSpot, Pipedrive, Gmail and Google Docs, using the connectors, exports or browser access available to it. PocketContext stores the resulting evidence and knowledge.
These are agent workflows, not bundled PocketContext integrations. Access depends on the source service, the agent’s tools and your permissions. Start with one source you already use and verify its workflow before adding others. For an existing Obsidian vault, an optional import script from the PocketContext source repository can bring a one-time copy; see Good to know.
Keep a useful trail.
Ask your agent to retain the source system, original record ID or link, and the time it read the information. A local copy answers questions about what was captured; a fresh sync is needed to know what changed later.
To use another interface, your agent can prepare Markdown or write selected content back through an authorized tool. Version 0.23.1 has no built-in exporter or automatic two-way sync. Define which system owns each field before reconciling changes.
04 / Make it a habit
Build on what you already know.
Once your sources are in one place, ask your agent to join information across them, check your own rules and propose updates. PocketContext’s authenticated, read-only SQL interface lets the agent query captured records together; changes go through the application API.
“Review my project pages. Find decisions without supporting evidence, dates that conflict across sources, and information that hasn’t been checked in a month. Give me a short list of proposed corrections.”
Use your agent’s scheduling feature for recurring work. PocketContext does not include a scheduler, model or built-in chat. Local queries avoid fetching the same remote records for every question; external syncs and model calls still follow their providers’ limits.
05 / Keep control
A small project folder.
A complete knowledge history.
PocketContext/
pocketcontext # The program (pocketcontext.exe on Windows)
pocketcontext.db # Knowledge and history
pocketcontext.json # Project configuration
storage/ # Original source filesThe setup prompts install the program into the project folder, beside the database, so the project keeps the release that can open it. The installers have no default location: you name the folder. For a project synced across operating systems, keep a versioned program on each computer outside the synced folder and let its profile select the database explicitly. Mac and Linux programs share a name. Keep a synced project folder downloaded on the computer that runs it, and if others can write to the folder, check the program’s version before using it. Machine-specific tokens and runtime files stay in a private cache. Back up the database, configuration, originals and matching program together, using a consistent snapshot after a clean pocketcontext stop. Keep the backup on a separate destination and verify that you can restore it.
The setup prompts do not automatically configure backups. On an always-on host, the database lives there; the connected client does not keep a second database. You can sign in to the same server from your other computers as clients, but only one computer should run a given project’s server at a time.
If your agent uses a cloud model, the content it reads may be sent to that provider. Local storage gives you control over the knowledge base; your agent’s data policies still apply.
A few practical questions
Good to know.
Do I need to move all my notes?
No. Begin with a few useful notes and keep your existing tools. Build a repeatable import workflow once you see value. Sources are preserved as evidence, and your agent can synthesize connected pages from them.
Can I bring over an existing Obsidian vault?
Yes, as a one-time copy, with some setup. Version 0.12.0 added an optional import script to the PocketContext source repository; it is not part of the program. It needs Python 3.10 or later and a copy of the source code matching your release, and works with a project on the same computer, for vaults whose collections keep original files in a raw/ folder beside their pages. It audits the vault before writing anything, then makes each collection a space: originals become sources, and notes become pages that keep their wording, links, images and footnotes. Imported pages are marked as needing verification, and their footnotes stay attribution rather than checked citations. Missing files and unresolved links are reported, not guessed, and an interrupted import can resume. It does not keep the vault in sync. Your agent’s PocketContext skill describes the workflow.
Can I read my knowledge from my phone?
Yes. Ask your agent for HTTPS hosting on a domain you control. PocketContext serves the reader and automatically manages its certificate in the same binary. Open the verified sign-in link in your phone browser; no PocketContext client or tunnel is needed. A domain and an internet-reachable, always-on host are required. Set up phone access.
Can I chat with my knowledge from my phone?
PocketContext has no built-in chat. With MCP enabled on your HTTPS domain, connect Gemini in its web settings, approve access and test the same connection in its mobile app. The phone reader still provides browsing, search and citations. Client availability and supported tools vary; follow the MCP setup.
Does it work with my agent?
The binary can install skills for Claude Code, Codex and Antigravity, or write a skill to a custom directory for another capable agent. An earlier Grok Bot two-computer workflow, using a separately installed Tailcat, has a recorded setup verification. Compatibility depends on command execution, file access and the ability to read and follow the skill; other agents need verification.
How do spaces and navigation work?
A project belongs to one person, and spaces simply partition your knowledge, for example by subject. There are no Personal or Company spaces, members or roles. A new project starts with one space, Default. Manage spaces in the reader, or your agent, can create, rename, archive and restore spaces and choose which one is the default. Archived spaces stay readable but accept no changes, and the default space cannot be archived. Your agent can organize published pages into topics and catalogs using page properties. A page can link to a page in another space; evidence and citations stay within each space.
Can I run the server and tunnel as one service?
Yes. For an initialized project, pocketcontext serve --headless --tunnel runs both in one foreground process. Your agent can configure one operating-system service to restart it after a failure and start it at boot. Stop an existing server before switching: this mode owns both components and refuses to attach to another server. Stopping the combined service stops the tunnel and cleanly writes the database back.
For independent lifetimes, pocketcontext tunnel serve remains available. It starts or reuses a compatible background server and leaves it running when the tunnel stops. Each component needs supervision for crash recovery. Neither tunnel mode creates a missing database. See the permanent-service guide for setup and migration.
What happens when setup runs through SSH?
Your agent finishes the command-line setup and skips launching a browser on the remote host. If you requested public HTTPS hosting, it verifies the domain and gives you a domain sign-in link for your phone. For a private desktop connection, it follows the client handoff below. A localhost link from that host does not automatically reach it from your laptop. If you already asked to connect your computer, setup continues to the client handoff; otherwise your agent offers that once. Paste the generated client prompt into an agent running on the computer where you want to browse. The desktop agent connects first, then generates a fresh reader sign-in link and opens it or shows it for you to click. Return to the server agent afterward and confirm that you could access the knowledge base, or share the desktop agent’s error report. A working tunnel alone does not confirm reader sign-in. Terminal-only clients can stay connected without opening a reader.
Can I keep using a project from an earlier version?
Yes for 0.11.x–0.23.0: their databases need no data migration to 0.23.1. A program update does not always change the database format. Have your agent stage and verify the new release, cleanly stop the project and its affected tunnels, and back up the database, configuration, original files and old program before explicitly replacing it. Then restart, check the running version and project identity, refresh the profile and skill, and check connected clients. The installer refuses an existing program unless the caller names its observed old version; it does not make backups or perform this workflow automatically.
For rollback, restore the complete backup with its matching program; do not assume replacing only the program is safe. Projects from 0.10.0 or earlier remain unsupported and are left unchanged. Keep their own release to read them and transfer needed content into a new project. See the upgrade and rollback guide.
Can different versions run on the same computer?
Yes. Keep one selected release for each project, with its own database folder and registered skill. The router chooses that project’s program; upgrading one project does not upgrade the others. Only one server may run a given project. Readers and remote forwards need available ports, and two remote servers using the same port cannot both be forwarded on one client without explicitly changing a server’s configuration. Use matching server and client releases and restart affected background processes after an upgrade.
How do I find the original evidence?
Use All pages for published knowledge and Sources for original files and their text, including uncited notes. Sources supports search, sorting and pagination. Markdown originals render in the reader; a citation can open and highlight its supporting passage. Pages can also link to an original file and show source images, which the reader displays only after checking their hash, with enlargement and download. Sidebar search follows the section you select.
Can I import PDFs, images or audio?
Yes. Version 0.23.1 stores them unchanged as originals, up to 50 MiB each, without reading them. Your agent converts each one to text with its own abilities, for example by reading the PDF or transcribing the audio, and records that text in PocketContext. The reader labels those passages as agent-derived text, not an exact copy, and its Needs extraction filter lists files still waiting for conversion. PocketContext never parses these formats or calls an external tool for them.
Is PocketContext an AI model?
No. It stores sources and structured knowledge, validates publications, and exposes authenticated search and SQL. Your agent supplies the reasoning and operates it through MCP or the CLI and skill.
Are the pages just Markdown files?
Page revisions contain Markdown bodies and structured JSON properties, linked citations and relationships. They live in the database with their history. An agent can render them as files, including front matter, using a separate export workflow.
Will every answer be correct?
Citations and revision history make answers easier to check. They do not guarantee that an agent interpreted a source correctly. Ask for the supporting passage and review uncertain conclusions before acting.
Where can I check the technical details?
Read the 0.23.1 README, data model, spaces, Obsidian import guide and release notes and downloads. The site’s setup prompts target this specific release.