Skip to main content

​
Overview

With GitHub integration, Ana can write and push context changes directly to a repository. Instead of manually copying context from chats, Ana suggests changes via pull requests — and you review them line by line before accepting or rejecting. This gives you a safe, auditable way to evolve your context over time.
Two Context Systems: TextQL supports both product-native context (managed in the Context Editor) and GitHub-based context. They complement each other and can be used together.

​
Why Use GitHub for Context?

The key benefit of GitHub integration is reviewable, version-controlled context updates. Ana can write and push context files on her own, but nothing lands in your main branch without your approval. You get:
  • Line-by-line review of every context change Ana proposes
  • Full version history so you can see how context evolves and revert if needed
  • PR-based collaboration where multiple team members can review and discuss changes
  • Automatic context writing — Ana creates branches and PRs without manual copy-paste

​
Product-Native Context vs. GitHub Context

FeatureProduct-Native ContextGitHub Context
Ease of Use✅ Simple UI, no technical setup⚠️ Requires GitHub knowledge
Version Control❌ No version history✅ Full Git history
Collaboration⚠️ Limited to TextQL users✅ GitHub PR workflow
File Organization⚠️ Flat library structure✅ Flexible directory structure
Context Updates⚠️ Manual copy from chat✅ Ana writes and pushes directly
Programmatic Access❌ UI only✅ Git/API access
Backup & Recovery⚠️ Managed by TextQL✅ You control backups

​
How It Works

When you connect Ana to a GitHub repository:
  1. Ana reads context from the repository at the start of each conversation
  2. Ana can create branches and pull requests to save new context
  3. You review and merge PRs to approve context changes
  4. Context updates are immediately available after merging
Always Review Pull Requests ManuallyEnabling GitHub integration allows Ana to automatically create branches and pull requests with context changes. Always manually review and approve all pull requests before merging to ensure changes align with your intended context. We don’t recommend auto-merging PRs from Ana without human review.

​
Setting Up GitHub Integration

1

Create a GitHub Repository

Create a new repository on GitHub (can be private or public). Name it something like ana-memory or textql-context.Create GitHub repository for Ana's memory
2

Create a Personal Access Token

Go to GitHub Settings > Developer settings > Personal access tokens and generate a new token.Generate GitHub personal access tokenConfigure the token:
  • Repository access: Select “Only select repositories” and choose the repository you just created
  • Expiration: Choose an appropriate duration (e.g., 30 days)
  • Permissions: Grant Contents: Read and Write so Ana can read context and write new context
Select repository scope permissionsClick Generate token and copy it — you won’t be able to see it again.
3

Add the Token to TextQL

Navigate to your TextQL settings > Configuration > Secrets Enabled > Manage Secrets and add the GitHub access token as a secret named ANA_CONTEXT_ACCESS_TOKEN.Add GitHub token to secretsThen add the configuration key for the repository:Configure repository access key
4

Configure the System Prompt

Add a system prompt to your organization’s configuration that tells Ana how to use the repository.
BEFORE doing ANYTHING - ESPECIALLY AT THE START OF A NEW CHAT:
1. Read overview.md from GitHub using ANA_CONTEXT_ACCESS_TOKEN
2. NEVER make assumptions about how APIs work
3. ALWAYS read supporting documentation from the context repo before using any API
4. Use provided Python code - DO NOT use web search for API documentation

GitHub Access Code:

import requests
import base64

GITHUB_PAT = SECRETS['ANA_CONTEXT_ACCESS_TOKEN']
headers = {
    'Authorization': f'token {GITHUB_PAT}',
    'Accept': 'application/vnd.github.v3+json'
}

# REPLACE WITH YOUR VALUES
REPO_OWNER = "your-github-username"
REPO_NAME = "your-repo-name"

# Reading files from the context repo:
url = f"https://api.github.com/repos/{REPO_OWNER}/{REPO_NAME}/contents/overview.md"
response = requests.get(url, headers=headers)
content = base64.b64decode(response.json()['content']).decode('utf-8')

Role:
Ana helps keep context updated via GitHub access token. She maintains persistent memory across sessions by reading and writing to the context repository.

When to Save:
Save when user says:
- "remember", "save", "store", "keep in mind"
- Provides preferences or instructions
- Likes a graph, visualization, or code cell
- Shares important information for future sessions

Save Procedure:
1. Create a new branch (never push to main)
2. Write to appropriate location (e.g., apis/{service-name}/ for API docs)
3. Create descriptive PR
4. Confirm to user
Configure organization context prompt

​
Demo: GitHub Context in Action

Here’s an example of how GitHub-based context works in practice. Ana references the context repository to understand previous work and team preferences: Ana accessing persistent memory for context Ana retrieves and applies stored context, providing responses aligned with previous work and established patterns: Ana applying persistent memory to deliver contextual results

​
Usage

Once configured, Ana can:
  • Save insights: “Ana, please save this analysis to your memory”
  • Retrieve context: Ana automatically references stored context at the start of each chat
  • Build knowledge: Over time, Ana builds a persistent knowledge base that grows across sessions

​
Best Practices

Never auto-merge PRs from Ana. Always manually review to ensure changes are accurate, don’t contain sensitive information, and will produce the desired behavior.
Create multiple focused files rather than one massive file. This makes PR reviews easier and version history clearer.
Configure GitHub branch protection to require PR reviews before merging and prevent direct commits to main.
For security, rotate your GitHub personal access token regularly and use an appropriate expiration window.

​
Troubleshooting

Ana can’t access the repository:
  • Verify the PAT has correct permissions (Contents: Read and Write)
  • Check the repository URL and owner are correct
  • Ensure the repository is not empty
  • Confirm the PAT hasn’t expired
Context not updating:
  • Verify changes are merged to the main branch
  • Check that files are in markdown format (.md)
  • Try starting a new chat to refresh context
Pull requests not being created:
  • Verify the PAT has write permissions
  • Check that repository settings allow PR creation
  • Ensure Ana has been instructed to save context via the system prompt

​
What’s Next?

Context Editor

Learn how to create and manage context documents in the product-native editor

What is Context?

Review the fundamentals of context in TextQL